Support categorized fragments, theme presets, block widths, and server-backed theme editing with onboarding and preview. Include Site Studio, design sources, specification and verification reports; remove the legacy studio-site example.
264 lines
15 KiB
Python
264 lines
15 KiB
Python
"""File theme validation, shared CSS and immutable releases without editable examples."""
|
|
|
|
import datetime as dt
|
|
import json
|
|
import os
|
|
import tempfile
|
|
import unittest
|
|
from pathlib import Path
|
|
from unittest.mock import patch
|
|
|
|
from theme_fixture import document, seed, write
|
|
|
|
from site_engine.build.pipeline import build_site, preview_page
|
|
from site_engine.core.registry import load_site
|
|
from site_engine.core.theme import default_theme, preset_catalog, resolve_theme, theme_css
|
|
from site_engine.core.validate import validate_workspace
|
|
from site_engine.errors import EngineError, Report
|
|
from site_engine.parsing.yamlio import dump_yaml
|
|
from site_engine.services.publish import rollback
|
|
|
|
NOW = dt.datetime(2026, 11, 13, 12, tzinfo=dt.UTC)
|
|
|
|
|
|
class ThemeTest(unittest.TestCase):
|
|
def resolve(self, overrides=None, preset="minimal"):
|
|
report = Report()
|
|
result = resolve_theme(document(preset, overrides), report)
|
|
return result, report
|
|
|
|
def test_exact_design_presets_and_independent_catalog_copies(self):
|
|
expected = {"minimal": ("#4255b9", 1180), "dark": ("#a48bfa", 1240),
|
|
"editorial": ("#82563e", 1040), "bold": ("#df466f", 1280),
|
|
"natural": ("#49775c", 1140), "custom": ("#6554ce", 1180)}
|
|
for name, (color, width) in expected.items():
|
|
with self.subTest(name=name):
|
|
overrides = {k: v for k, v in preset_catalog()[name].items() if k in ("colors", "type", "ui")} if name == "custom" else {}
|
|
theme, report = self.resolve(overrides, name)
|
|
self.assertTrue(report.ok, report.issues)
|
|
self.assertEqual(theme.tokens["colors"]["primary"], color)
|
|
self.assertEqual(theme.container.max_width, width)
|
|
catalog = preset_catalog()
|
|
catalog["dark"]["colors"]["primary"] = "modified"
|
|
self.assertEqual(preset_catalog()["dark"]["colors"]["primary"], "#a48bfa")
|
|
|
|
def test_deep_overrides_preserve_other_tokens(self):
|
|
theme, report = self.resolve({"colors": {"primary": "#123456"}, "ui": {"container": {"mode": "fluid", "gutter": {"mobile": 0}}}})
|
|
self.assertTrue(report.ok, report.issues)
|
|
self.assertEqual(theme.container.gutter.desktop, 32)
|
|
self.assertEqual(theme.container.gutter.mobile, 0)
|
|
self.assertEqual(theme.container.mode, "fluid")
|
|
self.assertEqual(theme.tokens["colors"]["surface"], "#ffffff")
|
|
self.assertIn("--color-primary: #123456;", theme_css(theme))
|
|
|
|
def test_custom_requires_complete_groups(self):
|
|
theme, report = self.resolve({"colors": {"primary": "#123456"}}, "custom")
|
|
self.assertIsNone(theme)
|
|
self.assertIn("E_THEME_CUSTOM", report.codes())
|
|
values = {k: v for k, v in preset_catalog()["custom"].items() if k in ("colors", "type", "ui")}
|
|
del values["ui"]["container"]["gutter"]["mobile"]
|
|
self.assertIn("E_THEME_CUSTOM", self.resolve(values, "custom")[1].codes())
|
|
|
|
def test_invalid_document_versions_and_unknown_keys(self):
|
|
for values in ({"schema": True}, {"schema": 2}, {"preset": []}, {"preset": "missing"},
|
|
{"preset_version": True}, {"preset_version": 2}, {"inline": {}}, {"overrides": None}):
|
|
with self.subTest(values=values):
|
|
report = Report()
|
|
self.assertIsNone(resolve_theme({**document(), **values}, report))
|
|
self.assertFalse(report.ok)
|
|
|
|
def test_invalid_group_shapes_report_instead_of_crashing(self):
|
|
for group in ("colors", "type", "ui", "custom_colors", "gradients"):
|
|
for value in (None, False, 0, [], "url(https://invalid)"):
|
|
with self.subTest(group=group, value=value):
|
|
theme, report = self.resolve({group: value})
|
|
self.assertIsNone(theme)
|
|
self.assertTrue(any(i.path.startswith("theme.yaml.overrides." + group) for i in report.errors))
|
|
|
|
def test_numeric_boundaries_and_strict_types(self):
|
|
for group, key, valid, invalid in (
|
|
("type", "scale", [.85, 1.3], [.84, 1.31, True, "1", float("nan"), float("inf"), 10**1000]),
|
|
("type", "line", [1.3, 1.9], [1.29, 1.91, None]),
|
|
("type", "headingWeight", [100, 900], [99, 901, 700.0, True]),
|
|
("ui", "radius", [0, 24], [-1, 25, "8px"]),
|
|
("ui", "spacing", [.8, 1.4], [.79, 1.41, False]),
|
|
):
|
|
for value in valid + invalid:
|
|
with self.subTest(group=group, key=key, value=value):
|
|
theme, report = self.resolve({group: {key: value}})
|
|
self.assertEqual(theme is not None, value in valid and type(value) is not bool)
|
|
self.assertEqual(report.ok, theme is not None)
|
|
|
|
def test_container_types_ranges_keys_and_legacy_numeric(self):
|
|
invalid = [1080, None, [], {"mode": "wide"}, {"mode": []}, {"max_width": 719},
|
|
{"max_width": 1921}, {"max_width": 1080.0}, {"max_width": True},
|
|
{"gutter": []}, {"gutter": {"mobile": -1}}, {"gutter": {"desktop": 97}},
|
|
{"gutter": {"tablet": "24"}}, {"gutter": {"phone": 16}}, {"width": 1200}]
|
|
for cn in invalid:
|
|
with self.subTest(container=cn):
|
|
theme, report = self.resolve({"ui": {"container": cn}})
|
|
self.assertIsNone(theme)
|
|
self.assertFalse(report.ok)
|
|
for mode in ("boxed", "fluid", "full"):
|
|
for width in (720, 1920):
|
|
theme, report = self.resolve({"ui": {"container": {"mode": mode, "max_width": width, "gutter": {"mobile": 0, "desktop": 96}}}})
|
|
self.assertTrue(report.ok)
|
|
self.assertEqual(theme.container.max_width, width)
|
|
|
|
def test_css_url_script_jinja_and_unapproved_font_are_rejected(self):
|
|
for override in (
|
|
{"colors": {"primary": "red; }body{display:none}"}},
|
|
{"colors": {"surface": "#fff"}}, {"colors": {"accent": "{{ x }}"}},
|
|
{"type": {"body": "url(https://example.org/font)"}},
|
|
{"type": {"heading": "</style><script>1</script>"}},
|
|
{"type": {"pair": "unknown"}}, {"ui": {"shadow": "anything"}},
|
|
{"ui": {"button": "gradient"}}, {"ui": {"css": "color:red"}},
|
|
):
|
|
with self.subTest(override=override):
|
|
theme, report = self.resolve(override)
|
|
self.assertIsNone(theme)
|
|
self.assertFalse(report.ok)
|
|
|
|
def test_named_colors_limits_and_reserved_names(self):
|
|
valid = {f"brand_{i}": "#123456" for i in range(24)}
|
|
theme, report = self.resolve({"custom_colors": valid})
|
|
self.assertTrue(report.ok)
|
|
self.assertIn("--color-brand-0: #123456", theme_css(theme))
|
|
for extra in ({**valid, "another": "#123456"}, {"primary": "#123456"},
|
|
{"a": "#123456"}, {"Bad_Name": "#123456"}, {"font;body": "#123456"},
|
|
{"brand": "url(x)"}, {1: "#123456"}):
|
|
with self.subTest(extra=extra):
|
|
self.assertFalse(self.resolve({"custom_colors": extra})[1].ok)
|
|
|
|
def test_gradients_validate_all_stops_and_disable_with_solid_fallback(self):
|
|
definition = {"type": "linear", "angle": 145, "stops": [{"at": 0, "color": "#112233"}, {"at": 55, "color": "#445566"}, {"at": 100, "color": "#778899"}]}
|
|
theme, report = self.resolve({"gradients": {"enabled": True, "definitions": {"hero": definition}}})
|
|
self.assertTrue(report.ok)
|
|
self.assertIn("W_THEME_GRADIENT_CONTRAST", report.codes())
|
|
self.assertIn("--hero-gradient: linear-gradient(145deg, #112233 0%, #445566 55%, #778899 100%);", theme_css(theme))
|
|
theme, _ = self.resolve({"gradients": {"enabled": False, "definitions": {"hero": definition}}})
|
|
self.assertNotIn("linear-gradient", theme_css(theme))
|
|
self.assertIn("--hero-gradient: #4255b9", theme_css(theme))
|
|
for key, value in (("type", "radial"), ("angle", -1), ("angle", 361), ("angle", True),
|
|
("stops", []), ("stops", [{"at": 0, "color": "#fff"}] * 2),
|
|
("stops", [{"at": 20, "color": "#112233"}, {"at": 20, "color": "#445566"}]),
|
|
("stops", [{"at": "0", "color": "#112233"}, {"at": 100, "color": "#445566"}])):
|
|
with self.subTest(key=key, value=value):
|
|
self.assertFalse(self.resolve({"gradients": {"definitions": {"hero": {**definition, key: value}}}})[1].ok)
|
|
self.assertFalse(self.resolve({"gradients": {"enabled": "true"}})[1].ok)
|
|
self.assertFalse(self.resolve({"gradients": {"definitions": {f"gradient_{i}": definition for i in range(13)}}})[1].ok)
|
|
|
|
def test_contrast_is_warning_and_defaults_have_no_gradients(self):
|
|
theme, report = self.resolve({"colors": {"text": "#ffffff", "muted": "#ffffff", "surface": "#ffffff", "background": "#ffffff"}})
|
|
self.assertIsNotNone(theme)
|
|
self.assertTrue(report.ok)
|
|
self.assertEqual(len(report.warnings), 3)
|
|
self.assertFalse(default_theme().tokens["gradients"]["enabled"])
|
|
|
|
|
|
class ThemeReleaseTest(unittest.TestCase):
|
|
def setUp(self):
|
|
temp = tempfile.TemporaryDirectory()
|
|
self.addCleanup(temp.cleanup)
|
|
self.work = Path(temp.name)
|
|
self.site, self.out = self.work / "site", self.work / "dist"
|
|
seed(self.site)
|
|
|
|
def test_no_theme_uses_safe_default_without_creating_file(self):
|
|
write(self.site, "site.yaml", "name: New site\n")
|
|
(self.site / "theme.yaml").unlink()
|
|
reg = load_site(self.site)
|
|
self.assertTrue(reg.report.ok)
|
|
self.assertEqual(reg.theme.document.preset, "minimal")
|
|
self.assertFalse((self.site / "theme.yaml").exists())
|
|
|
|
def test_bad_explicit_file_inline_config_and_malformed_yaml(self):
|
|
configs = [{"file": "missing.yaml"}, {"file": "../secret.yaml"}, {"file": "/tmp/secret"},
|
|
{"file": None}, {"file": ""}, {"tokens": {"color.primary": "#123456"}}, [], False]
|
|
for config in configs:
|
|
with self.subTest(config=config):
|
|
write(self.site, "site.yaml", dump_yaml({"name": "Invalid theme", "theme": config}))
|
|
self.assertFalse(load_site(self.site).report.ok)
|
|
write(self.site, "site.yaml", dump_yaml({"name": "Invalid theme", "theme": {"file": "theme.yaml"}}))
|
|
for text in ("[", "", "schema: 1\nschema: 1", "schema: 1\npreset: &x minimal\npreset_version: *x", "- item"):
|
|
with self.subTest(text=text):
|
|
write(self.site, "theme.yaml", text)
|
|
self.assertFalse(load_site(self.site).report.ok)
|
|
|
|
def test_theme_symlink_cannot_escape_site_root(self):
|
|
write(self.work, "outside.yaml", dump_yaml(document()))
|
|
(self.site / "theme.yaml").unlink()
|
|
(self.site / "theme.yaml").symlink_to(self.work / "outside.yaml")
|
|
self.assertIn("E_THEME_FILE", load_site(self.site).report.codes())
|
|
|
|
def test_all_presets_build_and_manifest_pins_effective_tokens(self):
|
|
for preset in preset_catalog():
|
|
with self.subTest(preset=preset):
|
|
overrides = {k: v for k, v in preset_catalog()[preset].items() if k in ("colors", "type", "ui")} if preset == "custom" else {}
|
|
write(self.site, "theme.yaml", dump_yaml(document(preset, overrides)))
|
|
result = build_site(self.site, self.out, now=NOW, keep=10)
|
|
manifest = json.loads((result.output_dir / "manifest.json").read_text())
|
|
self.assertEqual(manifest["theme"]["document"]["preset"], preset)
|
|
self.assertEqual(manifest["theme"]["document"]["preset_version"], 1)
|
|
self.assertTrue(manifest["render_hash"])
|
|
css = next((result.output_dir / "assets").glob("site.*.css")).read_text()
|
|
expected = manifest["theme"]["effective_tokens"]["colors"]["primary"]
|
|
self.assertIn("--color-primary: " + expected, css)
|
|
self.assertNotIn("data-preview-", (result.output_dir / "index.html").read_text())
|
|
|
|
def test_public_and_passive_preview_share_css_and_override_defaults_last(self):
|
|
result = build_site(self.site, self.out, now=NOW)
|
|
css = next((result.output_dir / "assets").glob("site.*.css")).read_text()
|
|
html, report = preview_page(self.site, "index", now=NOW)
|
|
self.assertTrue(report.ok, report.issues)
|
|
self.assertIn(css, html)
|
|
self.assertGreater(css.index("--color-primary:"), css.index("/* fragment: hero */"))
|
|
|
|
def test_contrast_warning_does_not_block_release(self):
|
|
write(self.site, "theme.yaml", dump_yaml(document(overrides={"colors": {"text": "#ffffff"}})))
|
|
result = build_site(self.site, self.out, now=NOW)
|
|
self.assertIn("W_THEME_CONTRAST", result.report.codes())
|
|
self.assertTrue(result.report.ok)
|
|
|
|
def test_invalid_theme_preserves_live_and_is_visible_to_preview(self):
|
|
original = build_site(self.site, self.out, now=NOW)
|
|
write(self.site, "theme.yaml", dump_yaml(document(overrides={"ui": {"container": 1080}})))
|
|
self.assertIn("E_THEME_SHAPE", validate_workspace(load_site(self.site)).codes())
|
|
for action in (lambda: build_site(self.site, self.out, now=NOW), lambda: preview_page(self.site, "index")):
|
|
with self.assertRaises(EngineError) as caught:
|
|
action()
|
|
self.assertIn("E_THEME_SHAPE", caught.exception.report.codes())
|
|
self.assertEqual(os.readlink(self.out / "current"), original.build_id)
|
|
|
|
def test_reproducibility_and_rollback_do_not_change_workspace(self):
|
|
first = build_site(self.site, self.out, now=NOW)
|
|
original_bytes = (first.output_dir / "manifest.json").read_bytes()
|
|
again = build_site(self.site, self.out, now=NOW)
|
|
self.assertEqual(first.build_id, again.build_id)
|
|
write(self.site, "theme.yaml", dump_yaml(document("dark")))
|
|
workspace = (self.site / "theme.yaml").read_bytes()
|
|
second = build_site(self.site, self.out, now=NOW)
|
|
self.assertNotEqual(first.build_id, second.build_id)
|
|
rollback(self.out, first.build_id)
|
|
self.assertEqual((self.site / "theme.yaml").read_bytes(), workspace)
|
|
self.assertEqual((self.out / "current/manifest.json").read_bytes(), original_bytes)
|
|
|
|
def test_render_resource_change_changes_id_with_same_source(self):
|
|
first = build_site(self.site, self.out, now=NOW)
|
|
reg = load_site(self.site)
|
|
reg.fragments["hero"].style += "\n.f-hero { padding-top: 5rem; }"
|
|
with patch("site_engine.build.pipeline.load_site", return_value=reg):
|
|
second = build_site(self.site, self.out, now=NOW)
|
|
self.assertEqual(first.source_hash, second.source_hash)
|
|
self.assertNotEqual(first.build_id, second.build_id)
|
|
self.assertTrue(first.output_dir.exists())
|
|
|
|
def test_existing_release_is_never_overwritten_on_collision(self):
|
|
first = build_site(self.site, self.out, now=NOW)
|
|
(first.output_dir / "index.html").write_text("Historical content")
|
|
with self.assertRaises(EngineError) as caught:
|
|
build_site(self.site, self.out, now=NOW)
|
|
self.assertIn("E_RELEASE_COLLISION", caught.exception.report.codes())
|
|
self.assertEqual((first.output_dir / "index.html").read_text(), "Historical content")
|
|
self.assertFalse(list(self.out.glob(".staging*")))
|