Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
"""Guards against showing an unpublished release, or generated body sections as the announcement."""
from __future__ import annotations
import http.server
import json
import re
import shutil
import subprocess
import sys
import threading
import time
from dataclasses import dataclass
from pathlib import Path
import pytest
from _en_catalog import en_string
from growth import assert_linear # tests/_shared, on sys.path via tests/conftest.py
REPO = Path(__file__).resolve().parents[2]
BACKEND = REPO / "studio/backend"
FRONTEND = REPO / "studio/frontend/src"
MODULE = BACKEND / "utils/release_notes.py"
BODIES = Path(__file__).parent / "fixtures/release_bodies"
PANEL = FRONTEND / "components/update/release-notes-panel.tsx"
NOTES_LAYOUT = FRONTEND / "components/update/update-notes-layout.ts"
NOTES_HOOK = FRONTEND / "hooks/use-release-notes.ts"
PREVIEW = FRONTEND / "lib/release-notes-preview.ts"
CODE_SPANS = FRONTEND / "lib/markdown-code-spans.ts"
LINKS = FRONTEND / "lib/release-body-links.ts"
LIST_COLUMNS = FRONTEND / "lib/markdown-list-columns.ts"
INLINE_COMMENTS = FRONTEND / "lib/markdown-inline-comments.ts"
WEB_BANNER = FRONTEND / "components/web/update-banner.tsx"
TAURI_BANNER = FRONTEND / "components/tauri/update-banner.tsx"
CARD_CAP = {
WEB_BANNER: "max-h-[calc(100dvh_-_2rem)]",
TAURI_BANNER: "max-h-[calc(100dvh_-_2rem_-_var(--studio-window-chrome-top,0px))]",
}
# An apostrophe in JSX text is prose, not a string delimiter; the frontend uses double quotes.
# A set, not a string: `"" in '"`'` is true for a substring.
_QUOTES = frozenset('"`')
_CALL = re.compile(r"[A-Za-z_$][\w$]*\(")
_IMPORTANT = re.compile(r"^!|!$")
def _split_variants(token: str) -> tuple[tuple[str, ...], str]:
"""Splits at colons outside brackets, since an arbitrary Tailwind value may hold its own colon."""
parts: list[str] = []
current: list[str] = []
depth = 0
for char in token:
if char in "[(":
depth += 1
elif char in "])":
depth -= 1
if char == ":" and depth == 0:
parts.append("".join(current))
current = []
else:
current.append(char)
parts.append("".join(current))
# `!min-h-0` and `min-h-0!` are `min-h-0` at a weight that beats the floor.
return tuple(parts[:-1]), _IMPORTANT.sub("", parts[-1])
def _tokens(source: str) -> list[tuple[tuple[str, ...], str]]:
"""Every class token in `source`, as (variants, utility)."""
return [_split_variants(token) for token in re.findall(r"""[^\s"'`]+""", source)]
def _applies(source: str, utility: str, *variants: str) -> bool:
"""Token-wise, not substring: a longer utility ending in this one does not match."""
for token_variants, token_utility in _tokens(source):
if token_utility == utility and set(variants) <= set(token_variants):
return True
return False
def _only_under(source: str, utility: str, *variants: str) -> bool:
"""Written at least once, and every occurrence sits under exactly these variants."""
found = False
for token_variants, token_utility in _tokens(source):
if token_utility != utility:
continue
if set(token_variants) != set(variants):
return False
found = True
return found
def _class_const(source: str, name: str) -> str:
"""Comments are stripped first, so a commented-out old declaration cannot answer for the live one."""
match = re.search(
rf'export const {re.escape(name)}\s*=\s*\n?\s*"([^"]*)"', _without_comments(source)
)
assert match, f"{name} is not an exported class constant"
return match.group(1)
_COMMENT_SPAN = re.compile(r"//[^\n]*|/\*.*?\*/", re.DOTALL)
# Shared with tests/studio/test_overlay_layering.py so both use the literal-aware scanner.
from jsx_tags import ( # noqa: E402
opening_tag as _opening_tag,
skip_literal as _skip_literal,
without_comments as _without_comments,
)
def _class_on_testid(source: str, testid: str) -> str:
"""Anchored on the data-testid, not on classes, so reordering or inserting a class cannot break it."""
clean = _without_comments(source)
start, end = _opening_tag(clean, clean.index(f'data-testid="{testid}"'))
return _class_value(clean[start:end], testid)
def _class_value(tag: str, what: str) -> str:
"""Reads className whether it is a literal or a cn() call, which renders the same classes."""
key = "className="
assert key in tag, f"{what} carries no className"
at = tag.index(key) + len(key)
if tag[at] == '"':
return tag[at + 1 : _skip_literal(tag, at) - 1]
assert tag[at] == "{", f"{what}'s className is neither a literal nor an expression"
return _always_rendered(tag[at + 1 : _balanced(tag, at) - 1])
def _arguments(call: str) -> list[str]:
"""The arguments of a call, split on its top-level commas."""
at = call.index("(")
parts: list[str] = []
current: list[str] = []
depth = 0
index = at
while index < len(call):
char = call[index]
if char in _QUOTES:
end = _skip_literal(call, index)
current.append(call[index:end])
index = end
continue
if char in "([{":
depth += 1
if depth == 1:
index += 1
continue
elif char in ")]}":
depth -= 1
if depth == 0:
break
elif char == "," and depth == 1:
parts.append("".join(current))
current = []
index += 1
continue
current.append(char)
index += 1
parts.append("".join(current))
return parts
def _always_rendered(expression: str) -> str:
"""Only a bare literal counts; a conditional class such as cn(open && ...) is not always rendered."""
text = expression.strip()
if text[:1] in _QUOTES and _skip_literal(text, 0) == len(text):
return text[1:-1]
if "(" not in text:
return ""
literals = []
for argument in _arguments(text):
part = argument.strip()
if part[:1] in _QUOTES and _skip_literal(part, 0) == len(part):
literals.append(part[1:-1])
elif _CALL.match(part) and _balanced(part, part.index("(")) == len(part):
# A nested `cn()` renders the same classes, so it must read the same.
literals.append(_always_rendered(part))
return " ".join(literals)
def _balanced(source: str, at: int) -> int:
"""The index just past the bracket group opening at `at`."""
depth = 0
index = at
while index < len(source):
char = source[index]
if char in _QUOTES:
index = _skip_literal(source, index)
continue
if char in "([{":
depth += 1
elif char in ")]}":
depth -= 1
if depth == 0:
return index + 1
index += 1
raise AssertionError("unbalanced brackets")
def _assert_classes(class_string: str, *rules: str) -> None:
"""Every one of `rules` is its own class in `class_string`."""
present = set(class_string.split())
missing = [rule for rule in rules if rule not in present]
assert not missing, f"{missing} missing from {class_string!r}"
# The scanners are run, not read: Node strips the types and nothing needs installing.
_TS_ALIAS = re.compile(r'"@/lib/([a-z-]+)"')
_TS_RUNNER = """
import { resolveReleaseBodyLinks } from "./release-body-links.ts";
import { releaseNotesPreview } from "./release-notes-preview.ts";
const chunks: Buffer[] = [];
process.stdin.on("data", (chunk: Buffer) => chunks.push(chunk));
process.stdin.on("end", () => {
const markdown = Buffer.concat(chunks).toString("utf8");
const result =
process.argv[2] === "links"
? resolveReleaseBodyLinks(markdown)
: releaseNotesPreview(markdown);
process.stdout.write(JSON.stringify(result));
});
"""
SAMPLE = """Intro prose, the announcement itself.
## Kimi K3
- a real section
## Updating / installing Unsloth
```bash
curl -fsSL https://unsloth.ai/install.sh | sh
```
## What's Changed
* Something by @someone in https://github.com/unslothai/unsloth/pull/1
**Full Changelog**: https://github.com/unslothai/unsloth/compare/v1...v2
"""
@dataclass(frozen = True)
class Section:
"""A heading and the lines under it, to the next heading of any level."""
version: str
heading: str
body: str
def sections(module, text: str) -> list[Section]:
"""Groups the shipped scanner's events under each heading; it alone decides what is a heading."""
found: list[Section] = []
bodies: list[list[str]] = []
for event in module.scan_blocks(text):
if isinstance(event, module.Heading):
if bodies and event.retract:
del bodies[-1][len(bodies[-1]) - event.retract :]
title = event.title.strip()
found.append(Section(version = title.split()[0] if title else "", heading = title, body = ""))
bodies.append([])
continue
if bodies:
bodies[-1].append(event.line)
return [
Section(version = entry.version, heading = entry.heading, body = "\n".join(body).strip())
for entry, body in zip(found, bodies)
]
def parse_sections(module, text: str) -> list[Section]:
"""`sections`, keeping only those whose heading starts with a version."""
return [entry for entry in sections(module, text) if module._parse_version(entry.version)]
def find_section(module, text: str, version: str) -> Section | None:
for entry in parse_sections(module, text):
if entry.version == version:
return entry
wanted = module._parse_version(version)
for entry in parse_sections(module, text):
if wanted is not None and module._parse_version(entry.version) == wanted:
return entry
return None
def releases_payload(*entries: dict) -> str:
"""A GitHub releases response, with the fields the selector reads."""
defaults = {
"draft": False,
"prerelease": False,
"name": "",
"body": "",
"html_url": "",
}
return json.dumps([{**defaults, **entry} for entry in entries])
@pytest.fixture(scope = "module")
def notes_module():
sys.path.insert(0, str(BACKEND))
try:
from utils import release_notes
finally:
sys.path.pop(0)
release_notes.reset_release_notes_cache()
yield release_notes
release_notes.reset_release_notes_cache()
@pytest.fixture
def serve_releases(notes_module, monkeypatch):
"""Serve a releases payload locally, and point the module at it."""
monkeypatch.delenv(notes_module.DISABLE_ENV_VAR, raising = False)
servers: list[http.server.HTTPServer] = []
def serve(
body: str,
status: int = 200,
headers: dict[str, str] | None = None,
reset: bool = True,
):
hits = {"count": 0}
class Handler(http.server.BaseHTTPRequestHandler):
def do_GET(self): # noqa: N802 - stdlib naming
hits["count"] += 1
payload = body.encode("utf-8")
self.send_response(status)
for name, value in (headers or {}).items():
self.send_header(name, value)
self.send_header("Content-Length", str(len(payload)))
self.end_headers()
self.wfile.write(payload)
def log_message(self, *_args):
pass
server = http.server.HTTPServer(("127.0.0.1", 0), Handler)
servers.append(server)
threading.Thread(target = server.serve_forever, daemon = True).start()
monkeypatch.setenv(
notes_module.RELEASES_URL_ENV_VAR,
f"http://127.0.0.1:{server.server_port}/releases",
)
if reset:
notes_module.reset_release_notes_cache()
return hits
yield serve
for server in servers:
server.shutdown()
server.server_close()
notes_module.reset_release_notes_cache()
@pytest.fixture
def isolated_releases(notes_module, monkeypatch):
"""Keep the module away from the network entirely."""
monkeypatch.setenv(notes_module.DISABLE_ENV_VAR, "1")
notes_module.reset_release_notes_cache()
yield notes_module
notes_module.reset_release_notes_cache()
def test_only_real_headings_become_sections(notes_module):
headings = [entry.heading for entry in sections(notes_module, SAMPLE)]
assert headings == ["Kimi K3", "Updating / installing Unsloth", "What's Changed"]
def test_section_body_stops_at_the_next_heading(notes_module):
entry = sections(notes_module, SAMPLE)[0]
assert "a real section" in entry.body
assert "install.sh" not in entry.body
def test_the_announcement_survives_and_the_generated_sections_do_not(notes_module):
stripped = notes_module.strip_release_body(SAMPLE)
assert "Intro prose" in stripped
assert "## Kimi K3" in stripped and "a real section" in stripped
for gone in (
"Updating / installing Unsloth",
"install.sh",
"What's Changed",
"pull/1",
"Full Changelog",
):
assert gone not in stripped
def test_response_reports_no_notes_without_markdown(isolated_releases):
"""Update checks are off, so there is no release and nothing to show."""
payload = isolated_releases.get_release_notes("2026.7.7")
assert payload["matched"] is False
assert payload["markdown"] is None
assert payload["version"] == "2026.7.7"
assert payload["release_notes_url"]
def test_the_offered_version_is_echoed_not_looked_up(notes_module, serve_releases):
"""No tag could match the PyPI version the pip popup offers, so it comes
back untouched for the UI to match a stale answer against."""
serve_releases(
releases_payload(
{
"tag_name": "v0.1.60-beta",
"name": "Meta Muse Glimmer",
"body": "The announcement.\n",
"html_url": "https://github.com/unslothai/unsloth/releases/tag/v0.1.60-beta",
"published_at": "2026-08-10T11:59:46Z",
}
)
)
payload = notes_module.get_release_notes("2026.8.11")
assert payload["version"] == "2026.8.11"
assert payload["tag"] == "v0.1.60-beta"
assert payload["heading"] == "Meta Muse Glimmer"
assert payload["html_url"].endswith("/releases/tag/v0.1.60-beta")
assert payload["matched"] is True and payload["source"] == "github"
assert "The announcement." in payload["markdown"]
def test_unsupported_version_query_is_rejected(isolated_releases):
assert isolated_releases.is_supported_version_query("2026.7.6") is True
for bad in ("../etc/passwd", "2026.7.6 OR 1", "", "a" * 80):
assert isolated_releases.is_supported_version_query(bad) is False
assert isolated_releases.get_release_notes("../etc/passwd")["matched"] is False
def test_the_newest_published_release_wins(notes_module, serve_releases):
"""Ordered by publication, never by tag: v0.1.60-beta was published after
v0.1.527-beta, so any numeric or SemVer sort picks the wrong one."""
serve_releases(
releases_payload(
{
"tag_name": "v0.1.527-beta",
"body": "older",
"published_at": "2026-08-09T17:14:42Z",
},
{
"tag_name": "v0.1.60-beta",
"body": "newer",
"published_at": "2026-08-10T11:59:46Z",
},
)
)
payload = notes_module.get_release_notes("2026.8.11")
assert payload["tag"] == "v0.1.60-beta"
assert "newer" in payload["markdown"]
@pytest.mark.parametrize(
"entry",
[
{"tag_name": "v9.9.9", "draft": True},
{"tag_name": "desktop-v0.1.60-beta"},
{"tag_name": "b8475"},
{"tag_name": "February-2026"},
],
)
def test_only_a_published_studio_release_is_shown(notes_module, serve_releases, entry):
serve_releases(
releases_payload(
{"body": "not an announcement", "published_at": "2026-08-11T00:00:00Z", **entry},
{
"tag_name": "v0.1.60-beta",
"body": "the announcement",
"published_at": "2026-08-10T11:59:46Z",
},
)
)
payload = notes_module.get_release_notes("2026.8.11")
assert payload["tag"] == "v0.1.60-beta"
assert "not an announcement" not in (payload["markdown"] or "")
@pytest.mark.parametrize("body", ['{"message": "Not Found"}', "[]", "not json at all"])
def test_a_payload_without_releases_is_an_error_not_a_crash(notes_module, serve_releases, body):
serve_releases(body)
payload = notes_module.get_release_notes("2026.8.11")
assert payload["matched"] is False
assert payload["error"], "the UI needs to know it can retry"
def test_a_release_with_no_announcement_shows_none(notes_module, serve_releases):
"""v0.1.527-beta's body is only the generated list, so nothing survives
stripping: the popup links out rather than showing an older release."""
serve_releases(
releases_payload(
{
"tag_name": "v0.1.527-beta",
"name": "Unsloth v0.1.527-beta",
"body": (BODIES / "v0.1.527-beta.md").read_text(encoding = "utf-8"),
"html_url": "https://github.com/unslothai/unsloth/releases/tag/v0.1.527-beta",
"published_at": "2026-08-09T17:14:42Z",
},
{
"tag_name": "v0.1.526-beta",
"body": "An earlier announcement.\n",
"published_at": "2026-08-04T16:06:43Z",
},
)
)
payload = notes_module.get_release_notes("2026.8.10")
assert payload["matched"] is False and payload["markdown"] is None
assert payload["tag"] == "v0.1.527-beta"
assert payload["html_url"].endswith("/releases/tag/v0.1.527-beta")
assert payload["error"] is None, "no notes is not a failure"
def test_longer_outer_fence_does_not_leak_a_fake_section(notes_module):
"""A ``` sample inside a ```` block must not close the block and let the
sample's heading be indexed as a real release."""
text = "## 1.0\n\n````md\n```\n## 9.9.9\n```\n````\n\n- real note\n"
assert [e.version for e in parse_sections(notes_module, text)] == ["1.0"]
assert find_section(notes_module, text, "9.9.9") is None
def test_tilde_fence_is_not_closed_by_backticks(notes_module):
text = "## 1.0\n\n~~~\n```\n## 9.9.9\n~~~\n\n- real\n"
assert [e.version for e in parse_sections(notes_module, text)] == ["1.0"]
def test_utf8_bom_does_not_hide_the_first_section(notes_module):
"""Editors on Windows can leave a BOM on the first line."""
assert [e.version for e in parse_sections(notes_module, "\ufeff## 1.0\n\n- x\n")] == ["1.0"]
@pytest.mark.parametrize("newline", ["\r\n", "\r"])
def test_non_unix_line_endings(notes_module, newline):
text = f"## 1.0{newline}{newline}- windows note{newline}"
entry = find_section(notes_module, text, "1.0")
assert entry is not None and "windows note" in entry.body
assert "\r" not in entry.body
def test_closing_fence_must_carry_nothing_after_it(notes_module):
"""CommonMark: a closer is the delimiter plus whitespace only. A ```` line
with trailing text inside a ```` block is content, not the end."""
text = "## 1.0\n\n````md\n```` not a closer\n## 9.9.9\n````\n\n- real\n"
assert [e.version for e in parse_sections(notes_module, text)] == ["1.0"]
info = "## 1.0\n\n```python\n## 9.9.9\n```\n\n- real\n"
assert [e.version for e in parse_sections(notes_module, info)] == ["1.0"]
@pytest.mark.parametrize(
"text",
[
"## 1.0\n\n- real\n\n<!--\n## 9.9.9\n\n- unpublished\n-->\n",
"## 1.0\n\n- real\n\n<!-- ## 9.9.9 -->\n",
],
)
def test_commented_out_sections_are_not_releases(notes_module, text):
"""Markdown does not render them, so they are not published notes."""
assert [e.version for e in parse_sections(notes_module, text)] == ["1.0"]
assert find_section(notes_module, text, "9.9.9") is None
def test_no_changelog_file_is_packaged_or_read():
"""The releases are the only source now. A file left in the packaging would
be a second one, editable in a checkout and stale in a wheel."""
assert not (REPO / "CHANGELOG.md").exists()
assert not (REPO / "_changelog_build.py").exists()
for name in ("pyproject.toml", "build.sh", ".gitignore"):
assert "CHANGELOG.md" not in (REPO / name).read_text(encoding = "utf-8")
source = MODULE.read_text(encoding = "utf-8")
assert "CHANGELOG.md" not in source and "changelog.py" not in source
def test_preview_keeps_identifier_underscores():
"""UNSLOTH_DISABLE_UPDATE_CHECK must not render as UNSLOTHDISABLEUPDATECHECK."""
src = PREVIEW.read_text(encoding = "utf-8")
assert "BOLD_UNDERSCORE" in src and "ITALIC_UNDERSCORE" in src
assert "parkCodeSpans" in src, "code spans are parked so their underscores survive"
assert "const EMPHASIS" not in src, "the blanket emphasis strip is gone"
def test_panel_prefers_the_page_the_notes_came_from():
"""The page the notes came from wins over the caller's URL and the changelog."""
src = PANEL.read_text(encoding = "utf-8")
assert "notes?.htmlUrl ?? releaseNotesUrl ?? notes?.releaseNotesUrl" in src
def test_remote_failure_is_reported_so_the_ui_can_retry(notes_module, monkeypatch):
"""An unreachable GitHub is retryable; "no notes published" is not."""
monkeypatch.delenv(notes_module.DISABLE_ENV_VAR, raising = False)
# Port 9 (discard) refuses fast, standing in for an unreachable host.
monkeypatch.setenv(notes_module.RELEASES_URL_ENV_VAR, "http://127.0.0.1:9/releases")
notes_module.reset_release_notes_cache()
try:
payload = notes_module.get_release_notes("2.0")
assert payload["matched"] is False
assert payload["error"], "remote failure must reach the UI"
finally:
notes_module.reset_release_notes_cache()
def test_preview_keeps_comparison_operators():
"""The tag strip must keep the operators in "Support Python <3.15 and >3.9"."""
src = PREVIEW.read_text(encoding = "utf-8")
assert "/<\\/?[a-zA-Z][^>]*>/g" in src, "tag strip must require a name character"
def test_preview_hides_commented_out_notes():
"""Unpublished notes inside <!-- --> are not rendered, so not previewed."""
src = PREVIEW.read_text(encoding = "utf-8")
assert "stripCommentSpans" in src and "COMMENT_OPEN" in src
def test_hook_treats_a_reported_failure_as_retryable():
src = NOTES_HOOK.read_text(encoding = "utf-8")
assert "next.error !== null" in src
def test_comment_delimiter_in_inline_code_is_literal(notes_module):
"""A note documenting `<!--` used to swallow every release below it."""
text = "## 2.0\n\n- Type `<!--` to begin a comment\n\n## 1.0\n\n- older\n"
assert [e.version for e in parse_sections(notes_module, text)] == ["2.0", "1.0"]
assert find_section(notes_module, text, "1.0") is not None
assert "older" not in find_section(notes_module, text, "2.0").body
def test_refresh_retries_a_cached_remote_failure(notes_module, serve_releases):
"""Retry must reach the network again rather than replay the cached failure."""
hits = serve_releases("", status = 500)
notes_module.get_release_notes("2.0")
notes_module.get_release_notes("2.0")
assert hits["count"] == 1, "the failure should be cached"
notes_module.get_release_notes("2.0", refresh = True)
assert hits["count"] == 2, "refresh must bypass the cached failure"
def test_a_rate_limit_is_not_retried_until_it_resets(notes_module, serve_releases):
"""A shared IP that has spent its 60 requests an hour gains nothing by
retrying: the request is refused and only pushes the reset further away."""
reset = str(int(time.time()) + 900)
hits = serve_releases(
'{"message": "API rate limit exceeded"}',
status = 403,
headers = {"X-RateLimit-Remaining": "0", "X-RateLimit-Reset": reset},
)
payload = notes_module.get_release_notes("2.0")
assert payload["matched"] is False and "rate limit" in payload["error"].lower()
notes_module.get_release_notes("2.0", refresh = True)
assert hits["count"] == 1, "refresh must not bypass a rate-limit lockout"
def test_a_rate_limit_deadline_is_bounded_not_just_its_first_wait(notes_module):
"""GitHub says not to request again before X-RateLimit-Reset, so the reset
wins over the back-off. Only the first wait used to be bounded, so the fetch
after it answered from the raw header and a skewed value parked the popup."""
import email.message
import urllib.error
def refused(seconds_out: float):
headers = email.message.Message()
headers["X-RateLimit-Remaining"] = "0"
headers["X-RateLimit-Reset"] = str(int(time.time() + seconds_out))
return urllib.error.HTTPError("url", 403, "rate limited", headers, None)
ceiling = notes_module.RELEASES_RATE_LIMIT_MAX_SECONDS
for seconds_out in (ceiling, 365 * 24 * 60 * 60):
notes_module.reset_release_notes_cache()
_, first = notes_module._http_error_source(refused(seconds_out))
_, next_wait = notes_module._fetch_latest_release()
assert first <= ceiling and next_wait <= ceiling
notes_module.reset_release_notes_cache()
_, short = notes_module._http_error_source(refused(120))
assert 60 <= short <= 180
def test_every_refusal_records_a_deadline_retry_has_to_wait_out(notes_module):
"""A secondary limit answers 403 or 429 with no `X-RateLimit-Remaining: 0`,
and at most a `Retry-After`. Only the primary path recorded a deadline, so
Retry dropped the cached failure and requested straight back into it."""
import email.message
import urllib.error
def refused(code: int, **headers: str):
message = email.message.Message()
for name, value in headers.items():
message[name] = value
return urllib.error.HTTPError("url", code, "refused", message, None)
ceiling = notes_module.RELEASES_RATE_LIMIT_MAX_SECONDS
cases = [
(refused(429), notes_module.RELEASES_RATE_LIMITED_TTL_SECONDS),
# Retry-After wins, being how a secondary limit states its wait.
(refused(403, **{"Retry-After": "120"}), 120),
(
refused(403, **{"Retry-After": "45", "X-RateLimit-Remaining": "0"}),
45,
),
]
for error, expected in cases:
notes_module.reset_release_notes_cache()
_, ttl = notes_module._http_error_source(error)
assert notes_module._rate_limited_until > time.time(), "no lockout recorded"
assert abs(ttl - expected) <= 2 and ttl <= ceiling
def test_the_page_asked_for_fits_under_the_read_cap(notes_module, serve_releases):
"""A release entry carries its whole body, so per_page and the byte cap are one decision: the
endpoint's maximum of 100 is near 4 MiB against a 2 MiB cap."""
import urllib.parse
query = urllib.parse.urlparse(notes_module.RELEASES_API_URL).query
per_page = int(urllib.parse.parse_qs(query)["per_page"][0])
largest = max(len(path.read_text(encoding = "utf-8")) for path in BODIES.glob("*.md"))
full_page = [
{
"tag_name": f"v0.1.{index}-beta",
"body": "x" * largest,
"published_at": f"2026-08-{index % 28 + 1:02d}T00:00:00Z",
}
for index in range(per_page)
]
payload = releases_payload(*full_page)
assert len(payload) < notes_module.RELEASES_MAX_BYTES, (
f"a full page of {per_page} is {len(payload) / 1024 / 1024:.1f} MiB "
f"against a {notes_module.RELEASES_MAX_BYTES / 1024 / 1024:.0f} MiB cap"
)
serve_releases(payload)
assert notes_module.get_release_notes("2026.8.11")["error"] is None
@pytest.mark.parametrize(
"heading",
["### macOS, Linux, WSL:", "### macOS / Linux / WSL", "### macOS/Linux/WSL"],
)
def test_platform_headings_split_on_a_slash_as_well_as_a_comma(notes_module, heading):
"""The install block splits its commands across per-platform headings, whose
separator is written either way."""
body = (
"The announcement.\n\n"
"### To update Unsloth or install a new Unsloth Studio, you must use:\n\n"
f"{heading}\n\n```\ncurl -fsSL https://unsloth.ai/install.sh | sh\n```\n\n"
"### Kimi K3\n\n- a real change\n"
)
stripped = notes_module.strip_release_body(body)
assert "install.sh" not in stripped and "macOS" not in stripped
assert "### Kimi K3" in stripped and "a real change" in stripped
def test_a_cached_release_answers_an_unchanged_response(notes_module, serve_releases):
"""GitHub answers a conditional request with 304 and no body, which is the
release already held rather than a failure."""
serve_releases(
releases_payload(
{
"tag_name": "v0.1.60-beta",
"body": "The announcement.\n",
"published_at": "2026-08-10T11:59:46Z",
}
),
headers = {"ETag": '"abc"'},
)
assert notes_module.get_release_notes("2.0")["matched"] is True
serve_releases("", status = 304, reset = False)
# Expired, not reset: the ETag and last good release must carry over.
notes_module._remote_cache.expires_at = 0
payload = notes_module.get_release_notes("2.0")
assert payload["matched"] is True and payload["tag"] == "v0.1.60-beta"
def test_hook_never_returns_another_versions_notes():
"""State still describes the previous version until the effect runs."""
src = NOTES_HOOK.read_text(encoding = "utf-8")
assert "notes.version === version" in src
assert "load(version, true)" in src, "retry must ask the backend to bypass its cache"
@pytest.mark.parametrize("indent", ["", " ", " ", " "])
def test_headings_and_fences_allow_commonmark_indentation(notes_module, indent):
"""Markdown renders up to three leading spaces, so the parser must agree."""
text = f"## 1.0\n\nOne.\n\n{indent}## 2.0\n\nTwo.\n"
assert [e.version for e in parse_sections(notes_module, text)] == ["1.0", "2.0"]
fenced = f"## 1.0\n\n{indent}```\n{indent}## 9.9.9\n{indent}```\n\n- real\n"
assert [e.version for e in parse_sections(notes_module, fenced)] == ["1.0"]
def test_four_space_indentation_is_code_not_structure(notes_module):
"""At four spaces Markdown switches to indented code, for both forms."""
assert [
e.version for e in parse_sections(notes_module, " ## 9.9.9\n\n## 1.0\n\n- real\n")
] == ["1.0"]
assert [
e.version
for e in parse_sections(notes_module, "## 1.0\n\n ```\n sample\n\n## 2.0\n\n- two\n")
] == ["1.0", "2.0"]
def test_desktop_notes_link_to_the_release_page_on_every_platform():
"""manualReleaseUrl is Linux-package only; the rest need the release page."""
hook = (FRONTEND / "hooks/use-tauri-update.ts").read_text(encoding = "utf-8")
assert "const releasePageUrl = info ?" in hook
banner = TAURI_BANNER.read_text(encoding = "utf-8")
assert "releaseNotesUrl={releasePageUrl ?? manualReleaseUrl}" in banner
provider = (FRONTEND / "app/provider.tsx").read_text(encoding = "utf-8")
assert "releasePageUrl={update.releasePageUrl}" in provider
def test_preview_matches_how_markdown_renders_prose_and_links():
"""Three rendering mismatches the preview must not reintroduce: wrapped
paragraphs split into fragments, autolinks eaten as tags, a lead cut short."""
src = PREVIEW.read_text(encoding = "utf-8")
assert "collector.paragraph = collector.paragraph" in src
assert "AUTOLINK" in src
assert "ABBREVIATIONS" in src and "INITIAL" in src
def test_preview_treats_code_as_literal():
"""Inside a code span, and inside an indented code block, Markdown renders
the text literally, so the preview must not transform or promote it."""
src = PREVIEW.read_text(encoding = "utf-8")
park = src.index("parkCodeSpans(markdown")
assert park < src.index("stripHtmlTags(\n parked")
assert "INDENTED_CODE_INDENT" in src
def test_desktop_updater_metadata_maps_published_field_names():
"""latest.json publishes Tauri's `notes`/`pub_date`; the manual Linux path
must read those, not `body`/`date`, or its release notes are always empty."""
rust = (REPO / "studio/src-tauri/src/desktop_update_policy.rs").read_text(encoding = "utf-8")
assert 'alias = "body"' in rust and "notes: Option<String>" in rust
assert 'alias = "date"' in rust and "pub_date: Option<String>" in rust
assert "body: metadata.notes" in rust and "date: metadata.pub_date" in rust
workflow = (REPO / ".github/workflows/release-desktop.yml").read_text(encoding = "utf-8")
assert "'notes': notes," in workflow, "workflow no longer publishes `notes`"
def test_backend_exposes_release_notes_route():
src = (BACKEND / "main.py").read_text(encoding = "utf-8")
assert '@app.get("/api/studio/release-notes")' in src
assert "is_supported_version_query" in src
def test_panel_is_scrollable_and_shows_only_the_stripped_notes():
src = PANEL.read_text(encoding = "utf-8")
assert "overflow-y-auto" in src, "release notes must scroll inside the popup"
assert "max-h-" in src, "the scroller needs a bounded height"
# latest.json's `notes` is install boilerplate, the same every release.
assert "fallbackMarkdown" not in src
assert "notes?.matched ? notes.markdown : null" in src
def test_notes_surface_is_borderless_and_lifts_in_dark_mode():
src = PANEL.read_text(encoding = "utf-8")
layout = NOTES_LAYOUT.read_text(encoding = "utf-8")
assert "border border-border" not in src, "the notes box is a fill, not a bordered box"
# Lighter than the card behind it: 0.06 white scaled by --contrast-wash-gain. The class must
# match whole, since a suffix, variant or `hover:` prefix makes Tailwind read another candidate.
assert re.search(
r"(?:(?<=[\s\"'`])|^)"
r"dark:bg-(?:white/\[0\.06\]"
r"|\[rgb\(255_255_255_/_calc\(0\.06\*var\(--contrast-wash-gain,\s*1\)\)\)\])"
r"(?=[\s\"'`]|$)",
layout,
), "the dark notes surface is no longer a 0.06 white lift"
# Streamdown's mt-6 clips the first heading against the scroller edge.
assert "[&>*>*:first-child]:mt-0" in src
assert "hover-scrollbar" in src
# Streamdown renders code at text-sm, twice this panel's body size.
assert "[&_code]:text-[0.92em]" in src
def test_hook_discards_notes_for_a_different_version():
src = NOTES_HOOK.read_text(encoding = "utf-8")
assert "notesVersion !== version" in src
def test_collapsed_panel_previews_the_top_bullets():
"""Collapsed popups show the headline changes without an extra click."""
preview = PREVIEW.read_text(encoding = "utf-8")
assert "RELEASE_NOTES_PREVIEW_ITEMS = 4" in preview
assert "collectBullets" in preview and "flush" in preview
assert "NESTED_INDENT_TOLERANCE" in preview
# Tag stripping repeats: one pass turns `<<b>b>` back into a live tag.
assert "while (out !== previous)" in preview
panel = PANEL.read_text(encoding = "utf-8")
assert "releaseNotesPreview" in panel
assert 'data-testid="update-release-notes-summary"' in panel
assert "enabled: true" in panel
def test_preview_highlights_the_leading_sentence():
"""Each bullet leads with its headline sentence, emphasised over the rest."""
preview = PREVIEW.read_text(encoding = "utf-8")
assert "splitLeadSentence" in preview
assert "SENTENCE_BREAK" in preview and "(?=" in preview
panel = PANEL.read_text(encoding = "utf-8")
layout = NOTES_LAYOUT.read_text(encoding = "utf-8")
assert "UPDATE_NOTES_LEAD_CLASS" in panel
assert '"font-medium text-foreground"' in layout
assert "item.rest" in panel
def _max_widths(source: str) -> set[str]:
"""Reads each max-w length at the default UI scale, unwrapping the calc() that scales it."""
return {_SCALED_PX.sub(r"\1", width) for width in re.findall(r"max-w-\[([^\]\s\"]+)\]", source)}
_SCALED_PX = re.compile(r"calc\((\d+(?:\.\d+)?px)\*var\(--ui-space-scale,1\)\)")
# `_max_widths` reads a bare 448px identically, so the scaled form is pinned raw.
_NOTES_WIDTH_SCALED = "max-w-[calc(448px*var(--ui-space-scale,1))]"
@pytest.mark.parametrize("banner", [WEB_BANNER, TAURI_BANNER])
def test_update_popups_share_the_notes_width(banner):
"""Every update popup uses the same width for its notes and action rows."""
source = banner.read_text(encoding = "utf-8")
assert "448px" in _max_widths(source)
assert (
_NOTES_WIDTH_SCALED in source and "max-w-[448px]" not in source
), "the notes width stopped scaling"
provider = (FRONTEND / "app/provider.tsx").read_text(encoding = "utf-8")
assert "400px" not in _max_widths(provider), "stack must not cap overlay width"
llama = (FRONTEND / "components/llama-update-banner.tsx").read_text(encoding = "utf-8")
assert "448px" in _max_widths(llama)
assert (
_NOTES_WIDTH_SCALED in llama and "max-w-[448px]" not in llama
), "the notes width stopped scaling"
assert "400px" not in _max_widths(llama)
def _shown_at(src: str, label: str) -> int:
"""Where a banner renders `label`: as literal English, or as a t("key") call en.ts maps to it."""
if label in src:
return src.index(label)
for call in re.finditer(r"""\bt\(\s*["']([\w.]+)["']\s*\)""", src):
try:
if en_string(call.group(1)) == label:
return call.start()
except (KeyError, ValueError):
continue
raise ValueError(f"the banner renders {label!r} neither literally nor through t()")
def test_a_label_is_found_literally_or_through_the_catalog():
assert _shown_at("<b>Show release notes</b>", "Show release notes") == 3
key = 'x {t("desktopUpdate.banner.showNotes")}'
assert _shown_at(key, "Show release notes") == key.index("t(")
with pytest.raises(ValueError):
_shown_at('{t("desktopUpdate.banner.later")}', "Remind me later")
@pytest.mark.parametrize("banner", [WEB_BANNER, TAURI_BANNER])
def test_banners_toggle_inline_release_notes(banner):
src = banner.read_text(encoding = "utf-8")
assert "ReleaseNotesPanel" in src
_shown_at(src, "Show release notes")
_shown_at(src, "Hide release notes")
assert "notesVersion" in src
@pytest.mark.parametrize(
"banner,toggle,action",
[
(WEB_BANNER, "web-update-release-notes-toggle", "web-update-snooze-button"),
(TAURI_BANNER, "tauri-update-release-notes-toggle", "Remind me later"),
],
)
def test_notes_toggle_shares_the_action_row(banner, toggle, action):
"""The toggle sits in the same row as the actions, not on its own line."""
src = banner.read_text(encoding = "utf-8")
row = src.index("mt-4 flex")
assert row < src.index(toggle) < _shown_at(src, action)
toggle_line = next(line for line in src.splitlines() if toggle in line)
toggle_block = src[src.index("Button", row) : src.index(toggle_line)]
assert "text-ui-13" in toggle_block and "whitespace-nowrap" in toggle_block
def test_headings_inside_a_raw_html_block_are_not_releases(notes_module):
"""<pre> content is literal, so a sample heading in it is not a section."""
text = "## 1.0\n\n<pre>\n## 9.9.9\n</pre>\n\n- real note\n"
assert [e.version for e in parse_sections(notes_module, text)] == ["1.0"]
assert "real note" in find_section(notes_module, text, "1.0").body
assert find_section(notes_module, text, "9.9.9") is None
def test_details_blocks_still_contain_markdown(notes_module):
"""<details> is a type 6 block, so headings inside it still count."""
text = "## 2.0\n\n<details>\n<summary>More</summary>\n\n- note\n\n</details>\n\n## 1.0\n\n- older\n"
assert [e.version for e in parse_sections(notes_module, text)] == ["2.0", "1.0"]
def test_inline_raw_html_tag_does_not_open_a_block(notes_module):
"""A block opens only at the start of a line; a tag mid-sentence is inline."""
text = "## 2.0\n\n- Warn when a <script> tag is pasted\n\n## 1.0\n\n- older\n"
assert [e.version for e in parse_sections(notes_module, text)] == ["2.0", "1.0"]
def test_preview_skips_raw_html_blocks():
src = PREVIEW.read_text(encoding = "utf-8")
assert "stripRawHtml" in src
assert "/^ {0,3}<(pre|script|style|textarea)" in src
def test_fence_inside_a_raw_html_block_is_literal(notes_module):
"""A stray ``` in a <pre> sample is literal; as a fence it hid later releases."""
text = "## 2.0\n\n<pre>\n```\n</pre>\n\n## 1.0\n\n- older\n"
assert [e.version for e in parse_sections(notes_module, text)] == ["2.0", "1.0"]
def test_raw_html_block_closes_on_any_of_the_four_tags(notes_module):
"""A type 1 block ends at the first of the four closers, matched or not."""
text = '## 1.0\n\n<script>\nconst sample = "</pre>";\n## 9.9.9\n</script>\n'
assert [e.version for e in parse_sections(notes_module, text)] == ["1.0", "9.9.9"]
@pytest.mark.parametrize("tag", ["details", "div", "table"])
def test_type_6_blocks_run_until_a_blank_line(notes_module, tag):
"""`<details>` holds Markdown only after a blank line closes the block."""
packed = f"## 1.0\n\n<{tag}>\n## 9.9.9\n</{tag}>\n\n- note\n"
assert [e.version for e in parse_sections(notes_module, packed)] == ["1.0"]
spaced = f"## 1.0\n\n<{tag}>\n\n## 2.0\n\n- note\n"
assert [e.version for e in parse_sections(notes_module, spaced)] == ["1.0", "2.0"]
def test_a_tag_only_line_cannot_interrupt_a_paragraph(notes_module):
"""Type 7 blocks do not interrupt a paragraph."""
text = "## 2.0\n\nSome prose.\n<span>\n\n## 1.0\n\n- older\n"
assert [e.version for e in parse_sections(notes_module, text)] == ["2.0", "1.0"]
def test_preview_joins_an_indented_continuation_line():
"""Four spaces only start code outside a paragraph; inside one it is a wrap."""
src = PREVIEW.read_text(encoding = "utf-8")
assert "!insideBlock && line.indent - line.column >= INDENTED_CODE_INDENT" in src
assert "opensDeepFence" in src
def test_preview_code_spans_need_a_matching_closer():
"""A closer is a run of the same length, so the inner backticks survive."""
src = CODE_SPANS.read_text(encoding = "utf-8")
assert "candidate === ticks" in src, "a closer is a run of the same length"
assert "stripPadding" in src, "one space of padding is dropped, as in Markdown"
def test_preview_skips_thematic_breaks():
"""`- - -` renders as a rule, so it must not take a preview slot."""
src = PREVIEW.read_text(encoding = "utf-8")
assert "THEMATIC_BREAK" in src
assert "THEMATIC_BREAK.test(visible)" in src
def test_preview_keeps_quoted_examples_out_of_the_headlines():
"""A quoted list is example output, not a change."""
src = PREVIEW.read_text(encoding = "utf-8")
assert "quoted: boolean" in src
assert "if (!line.quoted)" in src, "quoted bullets never become headlines"
def test_notes_panel_keeps_the_link_when_the_lookup_fails():
"""The release page can be reachable when the backend lookup is not."""
src = PANEL.read_text(encoding = "utf-8")
error_branch = src[src.index('if (state === "error")') :]
retry = error_branch.index("update-release-notes-retry")
assert error_branch.index("{link}") > retry, "link sits beside retry"
def test_hook_waits_for_the_desktop_auth_token():
"""A token not installed yet must not be recorded as a failed lookup."""
src = NOTES_HOOK.read_text(encoding = "utf-8")
assert "hasAuthToken()" in src and "AUTH_POLL_LIMIT" in src
def test_a_body_staged_as_a_comment_reads_as_unpublished(notes_module, serve_releases):
"""A release drafted inside <!-- --> renders as nothing, so it is unpublished."""
serve_releases(
releases_payload(
{
"tag_name": "v2.0",
"body": "<!-- not ready -->\n",
"published_at": "2026-08-10T00:00:00Z",
}
)
)
staged = notes_module.get_release_notes("2.0")
assert staged["matched"] is False and staged["markdown"] is None
assert staged["source"] is None, "nothing was shown, so nothing sourced it"
@pytest.mark.parametrize(
"body,visible",
[
("- note", True),
("<!-- staged -->", False),
("```\n```", True),
("<pre>\n</pre>", True),
(" ", False),
],
)
def test_visibility_check_only_hides_comments(notes_module, body, visible):
assert notes_module._renders_visibly(body) is visible
@pytest.mark.parametrize(
"block",
[
"<?php\n## 9.9.9\n?>",
"<![CDATA[\n## 9.9.9\n]]>",
"<!DOCTYPE\n## 9.9.9\n>",
],
)
def test_processing_instructions_and_declarations_are_literal(notes_module, block):
"""Raw block types 3 to 5 render literally, so a heading in one is a sample."""
text = f"## 1.0\n\n{block}\n\n- real note\n"
assert [e.version for e in parse_sections(notes_module, text)] == ["1.0"]
assert "real note" in find_section(notes_module, text, "1.0").body
def test_headings_need_a_space_or_tab_after_the_hashes(notes_module):
"""A non-breaking space after the hashes renders as text, not a heading."""
text = "## 1.0\n\n- real note\n\n## 9.9.9\n\n- not a release\n"
assert [e.version for e in parse_sections(notes_module, text)] == ["1.0"]
assert find_section(notes_module, text, "9.9.9") is None
tabbed = "## 1.0\n\n- one\n\n##\t2.0\n\n- two\n"
assert [e.version for e in parse_sections(notes_module, tabbed)] == ["1.0", "2.0"]
def test_preview_skips_every_raw_block_form():
"""The extractor tracks the same block forms as the parser."""
src = PREVIEW.read_text(encoding = "utf-8")
assert "RAW_BLOCKS" in src
assert "CDATA" in src and "[A-Za-z]" in src
@pytest.mark.parametrize("banner", [WEB_BANNER, TAURI_BANNER])
def test_expanded_popup_fits_a_short_viewport(banner):
"""A window under roughly 430px used to push the card's title off screen."""
panel = PANEL.read_text(encoding = "utf-8")
assert "min-h-0 flex-1" in panel, "notes height must follow the viewport"
src = banner.read_text(encoding = "utf-8")
assert CARD_CAP[banner] in src, "card is the backstop on tiny viewports"
def test_relative_release_body_links_point_at_the_repository():
"""Repository-relative links would resolve against Unsloth's own origin."""
src = LINKS.read_text(encoding = "utf-8")
assert "https://github.com/unslothai/unsloth/blob/main/" in src
assert "https://raw.githubusercontent.com/unslothai/unsloth/main/" in src
assert "ABSOLUTE" in src and "codeSpans" in src and "FENCE" in src
panel = PANEL.read_text(encoding = "utf-8")
assert "resolveReleaseBodyLinks" in panel
@pytest.mark.parametrize("query", ["latest", "main", "not-a-version", "abc"])
def test_unparseable_versions_are_rejected(notes_module, query):
"""A query that cannot parse is a bad request, not an empty result."""
assert notes_module.is_supported_version_query(query) is False
@pytest.mark.parametrize("query", ["2026.7.5", "v2026.7.5", "2026.07.5", "1.0.0rc1"])
def test_real_versions_are_still_accepted(notes_module, query):
assert notes_module.is_supported_version_query(query) is True
def test_reference_style_images_resolve_to_the_raw_host():
"""An image needs the raw file: the blob URL is an HTML page."""
src = LINKS.read_text(encoding = "utf-8")
assert "IMAGE_REFERENCE" in src
assert "imageLabels" in src
def test_collapsed_notes_surface_is_hidden_when_nothing_previews():
"""Notes that preview as nothing leave an empty strip, worse than none."""
src = PANEL.read_text(encoding = "utf-8")
assert "preview?.items.length === 0" in src
def test_a_fence_closer_accepts_only_spaces_and_tabs(notes_module):
"""A delimiter followed by a non-breaking space is content, not a closer."""
text = "## 1.0\n\n```\n```\u00a0\n## 9.9.9\n```\n\n- real note\n"
assert [e.version for e in parse_sections(notes_module, text)] == ["1.0"]
plain = "## 1.0\n\n```\nx\n```\t\n\n## 2.0\n\n- two\n"
assert [e.version for e in parse_sections(notes_module, plain)] == ["1.0", "2.0"]
for source in (PREVIEW, LINKS):
assert "/[^ \\t]/" in source.read_text(encoding = "utf-8")
def test_code_spans_close_on_a_run_of_equal_length():
"""`a``b [x](y.md)` is one code span, so the link inside it is literal."""
src = CODE_SPANS.read_text(encoding = "utf-8")
assert "candidate === ticks" in src, "closer length must match the opener"
assert "markdown-code-spans" in PREVIEW.read_text(encoding = "utf-8")
assert "markdown-code-spans" in LINKS.read_text(encoding = "utf-8")
def test_preview_decodes_entities_like_the_renderer():
"""Streamdown renders `AT&T` as AT&T, so the raw entity must not show."""
src = PREVIEW.read_text(encoding = "utf-8")
assert "NAMED_ENTITIES" in src and "decodeEntity" in src
# Decoded before code spans are restored, so code keeps the literal text.
assert src.index(".replace(ENTITY, decodeEntity)") < src.index(".replace(PARKED")
def test_release_notes_request_refreshes_an_expired_token():
"""A direct fetch cannot recover from a 401; authFetch refreshes first."""
src = NOTES_HOOK.read_text(encoding = "utf-8")
assert "authFetch(" in src
assert "getAuthToken" not in src
def test_preview_handles_the_desktop_updater_line_endings():
"""CRLF used to hide fences and promote a code sample to a headline."""
src = PREVIEW.read_text(encoding = "utf-8")
assert "LINE_ENDINGS" in src
assert "LINE_ENDINGS" in LINKS.read_text(encoding = "utf-8")
def test_preview_renders_reference_links_as_text():
"""`[text][label]` renders as a link, so its raw markup must not show."""
src = PREVIEW.read_text(encoding = "utf-8")
assert "LINK_REFERENCE" in src and "IMAGE_REFERENCE" in src
assert "DEFINITION" in src
def test_preview_treats_escaped_punctuation_as_literal():
"""`\\*not italic\\*` keeps its stars, and an escaped backtick opens no span."""
assert "ESCAPE" in PREVIEW.read_text(encoding = "utf-8")
assert "escaped(" in CODE_SPANS.read_text(encoding = "utf-8")
def test_link_resolver_skips_every_code_form():
"""Indented code and cross-line code spans render as code, so leave them."""
src = LINKS.read_text(encoding = "utf-8")
assert "INDENTED_CODE" in src
assert "codeSpans(masked)" in src
assert "definition.has(index)" in src
def test_badge_links_resolve_both_targets():
"""`[](link)`: the outer link needs a nested label to resolve."""
assert "NESTED_LABEL" in LINKS.read_text(encoding = "utf-8")
def test_in_flight_requests_are_identified_not_just_versioned():
"""Two requests for one version could resolve out of order."""
assert "requestIdRef" in NOTES_HOOK.read_text(encoding = "utf-8")
def test_notes_repair_the_shared_previews_width_reset():
"""MarkdownPreview clears max-width on descendants, so wide content escapes."""
src = PANEL.read_text(encoding = "utf-8")
assert "[&_img]:max-w-full" in src
assert "[&_[data-streamdown=link-safety-modal]>*]:max-w-md" in src
@pytest.mark.parametrize("banner", [WEB_BANNER, TAURI_BANNER])
def test_only_the_notes_region_scrolls(banner):
"""The dismiss control sits inside the card, so the card must not scroll."""
src = banner.read_text(encoding = "utf-8")
surface = _card_surface(src)
_assert_classes(surface, "flex", CARD_CAP[banner], "flex-col")
# Asserted as the absence of scrolling overflow, not presence of overflow-hidden: the
# browser card clips nothing at all.
assert not re.search(
r"(?<![\w-])overflow-(?:y-)?(?:auto|scroll)(?![\w-])", surface
), "the card scrolls, so its dismiss control can leave the viewport"
if banner == WEB_BANNER:
# Either class zeroes a flex item's automatic minimum, letting the rail cut the action row.
for zeroes_the_floor in ("min-h-0", "overflow-hidden"):
assert (
zeroes_the_floor not in surface.split()
), f"{zeroes_the_floor} puts the browser card's floor back to nothing"
else:
_assert_classes(surface, "min-h-0", "overflow-hidden")
layout = NOTES_LAYOUT.read_text(encoding = "utf-8")
_assert_classes(
_class_const(layout, "UPDATE_NOTES_ROOT_CLASS"),
"flex",
"min-h-0",
"flex-1",
"flex-col",
"overflow-hidden",
)
panel = PANEL.read_text(encoding = "utf-8")
assert "UPDATE_NOTES_EXPANDED_SCROLL_CLASS" in panel
_assert_classes(
_class_const(layout, "UPDATE_NOTES_EXPANDED_SCROLL_CLASS"),
"max-h-64",
"min-h-0",
"flex-1",
"overflow-y-auto",
)
# Without its own scroll, the collapsed bullets painted over the buttons in a small slot.
_assert_classes(
_class_on_testid(panel, "update-release-notes-summary"),
"min-h-0",
"flex-1",
"space-y-1",
"overflow-y-auto",
)
def test_a_comment_marker_in_prose_cannot_swallow_later_releases(notes_module):
"""A note that mentions `<!--` used to put the parser into comment state for
the rest of the file, hiding every release below it."""
text = (
"## 2026.8.0\n\n- Unsloth strips <!-- markers from pasted prompts.\n\n"
"## 2026.7.5\n\n- SECRET: an older release\n"
)
assert [e.version for e in parse_sections(notes_module, text)] == ["2026.8.0", "2026.7.5"]
assert "SECRET" not in find_section(notes_module, text, "2026.8.0").body
assert find_section(notes_module, text, "2026.7.5") is not None
hidden = "## 2.0\n\n<!--\n## 9.9.9\n-->\n\n- note\n"
assert [e.version for e in parse_sections(notes_module, hidden)] == ["2.0"]
def test_unmatched_backtick_runs_stay_linear(notes_module):
"""Rescanning the suffix per opener was quadratic: 800 never-closing runs
took 7.7s at 321 KB, and notes are reparsed on every popup request."""
line = "".join("`" * (i + 1) + "x" for i in range(800))
assert len(line) > 300_000
started = time.monotonic()
assert notes_module._code_span_ranges(line) == []
assert time.monotonic() - started < 2.0
def test_a_base_exception_releases_the_single_flight_flag(notes_module, monkeypatch):
"""The flag was cleared only after `except Exception`, so a BaseException
stranded it and every later caller waited out the full deadline."""
notes_module.reset_release_notes_cache()
def explode():
raise KeyboardInterrupt
monkeypatch.setattr(notes_module, "_fetch_latest_release", explode)
with pytest.raises(KeyboardInterrupt):
notes_module.get_latest_release()
assert notes_module._remote_fetching is False
notes_module.reset_release_notes_cache()
@pytest.mark.parametrize("marker", ["<!-->", "<!--->"])
def test_an_empty_comment_does_not_swallow_later_releases(notes_module, marker):
"""`<!-->` and `<!--->` are complete comments: the closer overlaps the
opener, so searching past it hid every release below."""
text = f"## 2.0\n\n- new stuff\n\n{marker}\n\n## 1.0\n\n- old stuff\n"
assert [e.version for e in parse_sections(notes_module, text)] == ["2.0", "1.0"]
assert find_section(notes_module, text, "1.0") is not None
assert "old stuff" not in find_section(notes_module, text, "2.0").body
assert "!line.includes(COMMENT_CLOSE)" in PREVIEW.read_text(encoding = "utf-8")
def test_an_unterminated_comment_still_hides_the_rest(notes_module):
"""The fix must not turn every `<!--` line into a no-op block."""
text = "## 2.0\n\n<!-- never closed\n\n## 1.0\n\n- old stuff\n"
assert [e.version for e in parse_sections(notes_module, text)] == ["2.0"]
def test_a_closing_delimiter_takes_its_whole_line(notes_module):
"""The closing line stays in the block, so a heading glued after it is not."""
for text in (
"## 1.0\n\n<!-- hidden -->## 9.9.9\n\n- note\n",
"## 1.0\n\n<pre>\nx\n</pre>## 9.9.9\n\n- note\n",
):
assert [e.version for e in parse_sections(notes_module, text)] == ["1.0"]
def test_an_exact_heading_is_never_shadowed(notes_module):
"""PEP 440 says 1.0 == 1.0.0, so the normalised match used to beat exact."""
text = "## 1.0.0\n\n- padded\n\n## 1.0\n\n- exact\n"
assert find_section(notes_module, text, "1.0").body == "- exact"
assert find_section(notes_module, text, "1.0.0").body == "- padded"
assert find_section(notes_module, "## 2026.7.6\n\n- x\n", "2026.07.6") is not None
def test_setext_headings_are_release_boundaries(notes_module):
"""A version over a line of dashes is the same heading in setext form."""
text = "2.0\n---\n\n- new\n\n1.0\n---\n\n- old\n"
assert [e.version for e in parse_sections(notes_module, text)] == ["2.0", "1.0"]
assert find_section(notes_module, text, "2.0").body == "- new"
assert [
e.version for e in parse_sections(notes_module, "## 2.0\n\n- a\n\n---\n\n## 1.0\n\n- b\n")
] == ["2.0", "1.0"]
def test_a_long_backtick_run_does_not_stall_the_parser(notes_module):
"""Parser time must grow linearly with a long backtick run; backtracking on it is superlinear."""
assert_linear(
lambda text: parse_sections(notes_module, text),
lambda n: "## 1.0\n\n- " + "`" * n + " <!--\n",
"backtick run",
# 5_000, so the big leg is the 20k previously measured. See assert_linear.
5_000,
)
def test_the_remote_fetch_has_a_total_deadline(notes_module):
"""The socket timeout resets per read, so a trickle could hold a worker."""
source = MODULE.read_text(encoding = "utf-8")
assert "deadline = time.monotonic() + RELEASES_TIMEOUT_SECONDS" in source
# read1 returns after one socket read, so the deadline is actually checked.
assert "response.read1(" in source
assert "Release notes are still loading." in source
def test_truncated_notes_close_their_fence(notes_module):
"""A blind slice could end inside a code block and break the rendering."""
body = "```\n" + "x\n" * 20_000 + "```\n"
payload = notes_module._notes_response(version = "1.0", markdown = body, source = "local")
assert payload["truncated"] is True
assert payload["markdown"].rstrip().endswith("```")
def test_the_opt_out_beats_the_developer_override():
"""The documented kill switch beats the dev switch, and the value must parse."""
source = (BACKEND / "utils/update_status.py").read_text(encoding = "utf-8")
assert "forced_version and not disabled and _is_version(forced_version)" in source
def test_a_list_item_over_dashes_is_not_a_setext_heading(notes_module):
"""`- first` over `---` is a list and a rule, not a setext heading."""
text = "## 1.0\n\n- first\n---\n\n- second\n"
assert [e.version for e in parse_sections(notes_module, text)] == ["1.0"]
body = find_section(notes_module, text, "1.0").body
assert "first" in body and "second" in body
setext = "2.0\n---\n\n- new\n\n1.0\n---\n\n- old\n"
assert [e.version for e in parse_sections(notes_module, setext)] == ["2.0", "1.0"]
def test_a_backtick_in_a_fence_info_string_is_not_a_fence(notes_module):
"""A backtick fence's info string may hold no backtick, so that line is prose."""
text = "## 2.0\n\n```bad`info\n\n## 1.0\n\n- old\n"
assert [e.version for e in parse_sections(notes_module, text)] == ["2.0", "1.0"]
assert [
e.version
for e in parse_sections(notes_module, "## 2.0\n\n```md\n## 9.9.9\n```\n\n## 1.0\n\n- old\n")
] == ["2.0", "1.0"]
for source in (PREVIEW, LINKS):
assert "info string" in source.read_text(encoding = "utf-8")
def test_preview_follows_commonmark_paragraph_rules():
"""Only an ordered list starting at 1 may interrupt a paragraph, an
unresolved reference keeps its brackets, and a quote owns its own."""
src = " ".join(PREVIEW.read_text(encoding = "utf-8").split())
assert "const interrupts = collector.current === null" in src
assert "!collector.quotedParagraph;" in src
assert "definedLabel" in src, "a reference only renders as text when defined"
assert "COMMENT_BLOCK_OPEN" in src
def test_link_resolver_leaves_raw_blocks_and_escapes_alone():
src = LINKS.read_text(encoding = "utf-8")
assert "RAW_HTML_OPEN" in src and "inRawHtml" in src
assert "isEscaped(line, opener)" in src
assert "BLOCK_LINE.test(structure)" in src
def test_code_span_closers_ignore_backslashes():
"""Escapes are not processed inside a code span, so a run after one closes."""
src = CODE_SPANS.read_text(encoding = "utf-8")
# Counted over the whole module: the scanner has moved above `codeSpans` once already.
calls = [
" ".join(line.split())
for line in src.splitlines()
if "escaped(" in line and not line.lstrip().startswith("function escaped(")
]
assert len(calls) == 1, f"only an opener can be escaped, called at {calls}"
assert '!== "`" || escaped(' in calls[0]
# The desktop card's incompressible height: a fixed part plus a part scaled by the font
# setting, since at 20px the action row wraps at every card width.
_SCALED_FLOOR_TAURI = "min-h-[calc(117px+93px*var(--ui-font-scale,1))]"
_NARROW_FLOOR_TAURI = "min-h-[calc(24px+224px*var(--ui-font-scale,1))]"
_NARROW = "max-[383px]"
# Floored while the notes panel is present, unsqueezable while it is not (#10229).
_NOTES_GATE = "has-[[data-slot=update-release-notes]]"
_BANNER_ROOT = re.compile(r'data-testid="(?:web|tauri)-update-banner"')
def _unpositioned_branch(text: str) -> str:
"""The rail-facing arm of the ternary, split at the depth-zero colon, counting nested ternaries."""
index = text.index("?", text.index("positioned")) + 1
pending = 1
depth = 0
while index < len(text):
char = text[index]
if char in _QUOTES:
index = _skip_literal(text, index)
continue
if char in "([{":
depth += 1
elif char in ")]}":
depth -= 1
elif char == "?" and depth == 0 and text[index + 1 : index + 2] not in (".", "?"):
pending += 1
elif char == ":" and depth == 0 and text[index - 1] != "?":
pending -= 1
if pending == 0:
return text[index + 1 :]
index += 1
raise AssertionError("the positioned card has no unpositioned branch")
def _card_slot(source: str) -> str:
"""The card root, found by its data-testid rather than a class, with comments stripped first."""
clean = _without_comments(source)
match = _BANNER_ROOT.search(clean)
assert match, "the update card has lost its data-testid"
start, end = _opening_tag(clean, match.start())
key = "className={cn("
tag = clean[start:end]
assert key in tag, "the card's root no longer builds its classes with cn()"
# Always-rendered classes only: a floor behind a constant is in the file but reaches no DOM.
return _always_rendered(_unpositioned_branch(clean[start + tag.index(key) : end]))
def _card_surface(source: str) -> str:
"""The first child's class string, bounded there so a later className cannot be read instead."""
clean = _without_comments(source)
match = _BANNER_ROOT.search(clean)
assert match, "the update card has lost its data-testid"
_, end = _opening_tag(clean, match.start())
child = clean.index("<", end)
# A fragment emits no element, so it is not the surface.
while clean[child + 1] == ">":
child = clean.index("<", child + 2)
start, child_end = _opening_tag(clean, child + 1)
return _class_value(clean[start:child_end], "the painted surface")
def _assert_floored(source: str, scaled: str, narrow: str, card: str) -> None:
"""The card keeps room for its header and buttons, in both of its states."""
# Read off the rail-facing root, so a floor on an inner box does not count.
root = _card_slot(source)
# `_only_under`: a gated floor stops applying over part of its range, an ungated twin
# reserves the empty height the gate was added to stop.
assert _only_under(
root, scaled, _NOTES_GATE
), f"the {card} card's floor is fixed, ungated, or gated more than its notes"
assert _only_under(
root, narrow, _NOTES_GATE, _NARROW
), f"the {card} card's floor misses the narrow card's extra button row"
assert _only_under(root, "shrink-0"), f"the rail can squeeze the {card} card with no notes open"
assert _only_under(
root, "shrink", _NOTES_GATE
), f"the {card} card cannot give up its notes' height, so the rail clips its buttons"
assert not _applies(
root, "min-h-0"
), f"min-h-0 lets the rail squeeze the {card} card past its floor"
def _assert_floors_itself(source: str, card: str) -> None:
"""The floor is measured, not written, but only holds while min-h-0 and overflow-hidden are absent."""
root = _card_slot(source)
surface = _card_surface(source)
for zeroes_the_floor in ("min-h-0", "overflow-hidden"):
assert (
zeroes_the_floor not in surface.split()
), f"{zeroes_the_floor} leaves the {card} card with no floor at all"
assert not re.search(
r"(?<![\w-])min-h-\[", surface + root
), f"the {card} card names a height again, which goes stale at the next type size"
assert _only_under(root, "shrink-0"), f"the rail can squeeze the {card} card with no notes open"
assert _only_under(
root, "shrink", _NOTES_GATE
), f"the {card} card cannot give up its notes' height, so the rail clips its buttons"
assert not _applies(
root, "min-h-0"
), f"min-h-0 lets the rail squeeze the {card} card past its floor"
RAIL_TESTID = "overlay-rail"
def _corner_rails(provider: str) -> list[str]:
"""Finds rails by data-testid, not by classes, so moving a rail's corner cannot make it unfindable."""
return [_class_value(tag, RAIL_TESTID) for tag in _rail_openings(provider)]
def _rail_openings(provider: str) -> list[str]:
"""The opening tag of each rail, comments already blanked."""
clean = _without_comments(provider)
tags = []
at = clean.find(f'data-testid="{RAIL_TESTID}"')
while at != -1:
start, end = _opening_tag(clean, at)
tags.append(clean[start:end])
at = clean.find(f'data-testid="{RAIL_TESTID}"', end)
return tags
# Both Tailwind padding spellings, including the `[padding:` arbitrary form; the required `-`
# keeps pointer-events-none, peer-* and place-items-* out.
_PADS = re.compile(r"p[xytblrse]?-|\[padding[-:]")
def _rail_class_tokens(tag: str) -> list[str]:
"""Every literal, conditionals included: a prohibition must see overrides that render only sometimes."""
key = "className="
at = tag.index(key) + len(key)
if tag[at] == '"':
expression = tag[at : _skip_literal(tag, at)]
else:
expression = tag[at + 1 : _balanced(tag, at) - 1]
tokens: list[str] = []
i = 0
while i < len(expression):
if expression[i] in _QUOTES:
end = _skip_literal(expression, i)
tokens += expression[i + 1 : end - 1].split()
i = end
else:
i += 1
return tokens
def _rail_padding(tag: str) -> dict[str, str]:
"""Maps each padding side to the constant it is set from, so a wrong-constant binding is caught."""
return {
prop: const
for prop, const in re.findall(r"\b(padding(?:Top|Bottom|Left|Right)): (\w+)", tag)
}
def _rail_style_px(provider: str, name: str) -> int:
"""The px value of one of the rail's spacing constants, read from its definition."""
found = re.search(rf"^const {name} = (\d+);", provider, re.MULTILINE)
assert found, f"{name} is gone from provider.tsx, so the rail's spacing is unreadable"
return int(found.group(1))
def _capped_rails(provider: str) -> int:
"""Counts rails capped to the full viewport; their gutters are inline style, not the class."""
# `md:max-h-[100dvh]` contains the utility but leaves smaller viewports uncapped.
# The desktop rail stops below the window chrome; there is none in the browser.
caps = ("max-h-[100dvh]", "max-h-[calc(100dvh-var(--studio-window-chrome-top,0px))]")
return sum(1 for rail in _corner_rails(provider) if any(_only_under(rail, c) for c in caps))
def test_the_class_matchers_tell_a_gated_rule_from_an_ungated_one():
"""The matchers must tell a gated rule from an ungated one, since the floor checks rely on them."""
gated = "max-[383px]:has-[[data-slot=update-release-notes]]:min-h-[calc(1px+2px)]"
assert _split_variants(gated) == (
("max-[383px]", "has-[[data-slot=update-release-notes]]"),
"min-h-[calc(1px+2px)]",
), "a bracketed variant's own colon splits the token"
assert _applies(gated, "min-h-[calc(1px+2px)]", "max-[383px]")
assert _applies(gated, "min-h-[calc(1px+2px)]", "max-[383px]", "has-[[data-slot=x]]") is False
assert _applies("min-h-[calc(1px+2px)]", "min-h-[calc(1px+2px)]", "max-[383px]") is False
assert _applies("min-h-0", "h-0") is False
assert _applies("md:shrink-0", "shrink-0"), "the absence check must see a gated rule"
assert _only_under("md:shrink-0", "shrink-0") is False
assert _only_under("flex shrink-0 flex-col", "shrink-0")
assert _only_under("has-[x]:min-h-4", "min-h-4", "has-[x]")
assert _only_under("md:has-[x]:min-h-4", "min-h-4", "has-[x]") is False
assert _only_under("has-[x]:min-h-4 min-h-4", "min-h-4", "has-[x]") is False
assert _only_under("flex", "min-h-4", "has-[x]") is False, "absent is not satisfied"
for important in ("!min-h-0", "min-h-0!"):
assert _split_variants(important)[1] == "min-h-0"
assert _applies(important, "min-h-0"), f"{important} escapes the prohibition"
def test_the_class_anchors_do_not_depend_on_any_order():
"""An anchor that needs an attribute or a branch to keep its place is the
same brittleness one level up, so both are read structurally."""
# An arrow function's `>` does not end the opening tag, and comparisons are not elements.
for tag in (
'<ul className="a b" data-testid="x" onClick={() => go()}>',
'<ul onClick={() => go()} data-testid="x" className="a b">',
'<ul disabled={count < limit} className="a b" data-testid="x">',
'<ul disabled={count < limit} data-testid="x" className="a b">',
):
assert _class_on_testid(tag, "x") == "a b", tag
branch = _unpositioned_branch('positioned ? "fixed dark:bg-card" : cn("rail shrink-0")')
assert "rail" in branch and "fixed" not in branch
# Only classes rendered in every state count; a constant guard leaves text but renders nothing.
assert _class_value('<div className="a b">', "x") == "a b"
assert _class_value('<div className={cn("a b")}>', "x") == "a b"
assert _class_value('<div className={cn("a b", open && "c")}>', "x").split() == ["a", "b"]
assert _class_value('<div className={cn(false && "a", "b")}>', "x").split() == ["b"]
assert _class_value('<div className={cn(open ? "a" : "z", "b")}>', "x").split() == ["b"]
# Comments can hold an apostrophe or unmatched brace, and the banners' comment names `shrink-0`.
for comment in ("// notes don't shrink", "/* an unmatched } is prose */"):
tag = f'<ul {comment}\n className="a b" data-testid="x">'
assert _class_on_testid(tag, "x") == "a b", comment
blanked = _without_comments("/* shrink-0 */ flex")
assert blanked.split() == ["flex"], "a class named in prose still reads as a class"
assert len(blanked) == len("/* shrink-0 */ flex"), "blanking a comment moved every later index"
# A `//` inside a literal is a URL, not a comment.
url = '"bg-[url(https://example.com/a.svg)] flex" // gone'
assert _without_comments(url).rstrip() == '"bg-[url(https://example.com/a.svg)] flex"'
def test_the_overlay_stack_fits_the_viewport():
"""A static cap, not a measured one: a cap computed from other overlays moves it off its corner."""
provider = (FRONTEND / "app/provider.tsx").read_text(encoding = "utf-8")
# Counted by layer, not literal z-index: the overlay rail reads its depth from Z_LAYER.
stacks = provider.count("zIndex: Z_LAYER.OVERLAY_STACK")
assert stacks, "the bottom-right overlay stack is gone"
assert len(_corner_rails(provider)) == stacks, "a rail left its bottom-right corner"
assert _capped_rails(provider) == stacks, "every stack is capped"
panel = (FRONTEND / "features/hub/download-manager/download-manager-panel.tsx").read_text(
encoding = "utf-8"
)
assert "flex min-h-0" in panel
# The update card's header and buttons are fixed and only its notes yield, so it floors.
_assert_floors_itself(WEB_BANNER.read_text(encoding = "utf-8"), "browser")
# The floors can exceed the cap at large type sizes, so the rail must scroll.
assert provider.count("overflow-y-auto") >= stacks, "a capped stack spills its cards"
def test_both_rails_are_still_pinned_to_the_bottom_right_corner():
"""Corner is asserted here: finding rails by testid alone would return one that had wandered."""
provider = (FRONTEND / "app/provider.tsx").read_text(encoding = "utf-8")
rails = _corner_rails(provider)
assert len(rails) == 2, f"expected the browser and desktop rails, found {len(rails)}"
for rail in rails:
# _only_under, not _applies: a gated `md:fixed` would leave the rail out of the corner.
# The rail's transparent gutters must not swallow clicks; cards opt back in with
# pointer-events-auto.
assert _only_under(
rail, "pointer-events-none"
), f"the rail stopped passing clicks through: {rail!r}"
assert _only_under(rail, "fixed"), f"the rail is no longer always viewport-fixed: {rail!r}"
assert _only_under(rail, "bottom-0"), f"the rail can leave the bottom edge: {rail!r}"
assert _only_under(rail, "right-0"), f"the rail can leave the right edge: {rail!r}"
def test_the_rail_gutters_come_out_of_the_cap_and_not_the_cards():
"""Gutters are inline px, not rem utilities, so the rail stays in its corner at any type size."""
provider = (FRONTEND / "app/provider.tsx").read_text(encoding = "utf-8")
top = _rail_style_px(provider, "STACK_SHADOW_GUTTER_TOP")
bottom = _rail_style_px(provider, "STACK_SHADOW_GUTTER_BOTTOM")
left = _rail_style_px(provider, "STACK_SHADOW_GUTTER_LEFT")
inset = _rail_style_px(provider, "STACK_CARD_INSET_RIGHT")
assert top and bottom and left and inset, "a rail gutter went to zero, so shadows clip"
# The deepest card shadow is 0 8px 28px -6px: 22px left of the card and 14px above it.
assert left >= 22, f"the left gutter {left}px is inside the card shadow's 22px reach"
assert top >= 14, f"the top gutter {top}px is inside the card shadow's 14px reach"
expected = {
"paddingTop": "STACK_SHADOW_GUTTER_TOP",
"paddingBottom": "STACK_SHADOW_GUTTER_BOTTOM_PAST_COMPOSER",
"paddingLeft": "STACK_SHADOW_GUTTER_LEFT",
"paddingRight": "STACK_CARD_INSET_RIGHT_PAST_PANEL",
}
assert re.search(
r"const STACK_CARD_INSET_RIGHT_PAST_PANEL =\s*`calc\(\$\{STACK_CARD_INSET_RIGHT\}px \+ var\(",
provider,
), "the rail's right padding is no longer the px card inset plus the panel width"
assert re.search(
r"const STACK_SHADOW_GUTTER_BOTTOM_PAST_COMPOSER =\s*`calc\(\$\{STACK_SHADOW_GUTTER_BOTTOM\}px \+ var\(",
provider,
), "the rail's bottom padding is no longer the px gutter plus the composer clearance"
openings = _rail_openings(provider)
assert len(openings) == 2, f"expected the browser and desktop rails, found {len(openings)}"
for tag in openings:
# The exact binding per rail: a count of STACK_ names would accept the wrong constant.
assert (
_rail_padding(tag) == expected
), f"a rail's padding is not bound to its own constant: {_rail_padding(tag)}"
# No padding utility in any spelling: the inline px style owns padding, and Tailwind padding is
# either rem-scaled (#8082) or, with !important, overrides it.
for tag in _rail_openings(provider):
for token in _rail_class_tokens(tag):
utility = _split_variants(token)[1]
assert not _PADS.match(utility), (
f"the rail carries the padding utility {token!r}; its padding is the inline "
f"px style, and a class here is rem-scaled or !important-overrides it (#8082)"
)
def test_the_desktop_stack_is_capped_like_the_browser_one():
"""The download panel shares the desktop stack, left uncapped before now."""
provider = (FRONTEND / "app/provider.tsx").read_text(encoding = "utf-8")
assert len(_corner_rails(provider)) == 2, "both rails sit in the bottom-right corner"
assert _capped_rails(provider) == 2, "both stacks are capped"
tauri = TAURI_BANNER.read_text(encoding = "utf-8")
_assert_floored(tauri, _SCALED_FLOOR_TAURI, _NARROW_FLOOR_TAURI, "desktop")
def test_the_rail_offset_is_not_computed():
"""Offset and cap must not be computed in JS, or the rail drifts when the composer grows."""
provider = (FRONTEND / "app/provider.tsx").read_text(encoding = "utf-8")
for banned in ("useStackGeometry", "stackGeometry", "stack.bottom", "stack.maxHeight"):
assert banned not in provider, f"the rail is placed from JS again ({banned})"
store = (FRONTEND / "features/settings/stores/monitor-frame-store.ts").read_text(
encoding = "utf-8"
)
assert "stackBottomInset" not in store, "the dodge arithmetic is back in the frame store"
def test_desktop_notes_are_not_keyed_by_the_pinned_backend_version():
"""The banner asks with the Unsloth version it offers. `pypi_version` stays
in latest.json as the backend pin preflight checks, not a notes key."""
banner = TAURI_BANNER.read_text(encoding = "utf-8")
assert "info?.version?.replace(LEADING_V" in banner
assert "pypiVersion" not in banner, "notes are no longer keyed by the backend release"
workflow = (REPO / ".github/workflows/release-desktop.yml").read_text(encoding = "utf-8")
assert "'pypi_version': os.environ['PYPI_VERSION']" in workflow
rust = (REPO / "studio/src-tauri/src/desktop_update_policy.rs").read_text(encoding = "utf-8")
assert "pypi_version: Option<String>" in rust
hook = NOTES_HOOK.parent.joinpath("use-tauri-update.ts").read_text(encoding = "utf-8")
assert "rawPypiVersion(update.rawJson)" in hook
def test_one_slow_read_cannot_outlast_the_fetch_budget(notes_module):
"""The socket timeout is per operation, so two slow reads doubled the wait."""
source = MODULE.read_text(encoding = "utf-8")
assert "_limit_read(response, remaining)" in source
assert "sock.settimeout(max(remaining, _RELEASES_MIN_READ_SECONDS))" in source
def test_a_heading_indented_into_a_list_item_is_not_a_release(notes_module):
"""CommonMark keeps a heading at the item's content column inside the item.
Checked against markdown-it (commonmark preset)."""
text = "## 1.0\n\n- Example:\n ## 9.9.9\n\n- after\n"
assert [e.version for e in parse_sections(notes_module, text)] == ["1.0"]
body = find_section(notes_module, text, "1.0").body
assert "9.9.9" in body and "after" in body
left = "## 1.0\n\n- Example:\n ## 2.0\n"
assert [e.version for e in parse_sections(notes_module, left)] == ["1.0", "2.0"]
def test_a_closed_list_stops_holding_headings(notes_module):
"""Only an open item nests a heading, so a dedented block hands it back."""
def versions(text):
return [e.version for e in parse_sections(notes_module, text)]
assert versions("## 1.0\n\n- Example:\n\nText.\n\n ## 2.0\n") == ["1.0", "2.0"]
assert versions("## 1.0\n\n- Example:\n## 2.0\n ## 3.0\n") == ["1.0", "2.0", "3.0"]
assert versions("## 1.0\n\n- Example:\n Text.\n---\n ## 2.0\n") == ["1.0", "2.0"]
assert versions("## 1.0\n\n- Example:\n```\n```\n ## 2.0\n") == ["1.0", "2.0"]
assert versions("## 1.0\n\n-\n\n ## 2.0\n") == ["1.0", "2.0"]
def test_a_version_line_is_not_an_ordered_list_marker(notes_module):
"""`2.` needs whitespace after it, or every setext version reads as an item."""
text = "2.0\n---\n\n- new\n\n1.0\n---\n\n- old\n"
assert [e.version for e in parse_sections(notes_module, text)] == ["2.0", "1.0"]
# An ordered item interrupts a paragraph only when it starts at 1.
assert [
e.version for e in parse_sections(notes_module, "## 1.0\n\nText.\n9) one\n ## 2.0\n")
] == ["1.0", "2.0"]
def test_a_wrapped_setext_heading_is_still_a_release(notes_module):
"""CommonMark promotes the whole paragraph, so a wrapped heading keeps its
version in the first token. Reading only the last line lost the release."""
text = "2026.7.5 - Release\nJuly 25\n---\n\n- note\n"
entries = parse_sections(notes_module, text)
assert [e.version for e in entries] == ["2026.7.5"]
assert entries[0].body == "- note"
assert "July 25" not in entries[0].body
def test_a_lowercase_declaration_is_not_a_raw_block(notes_module):
"""Only `<!` plus an uppercase letter opens one, so `<!note` is prose."""
assert [e.version for e in parse_sections(notes_module, "<!note\n\n## 1.0\n\n- real\n")] == [
"1.0"
]
assert [
e.version for e in parse_sections(notes_module, "<!DOCTYPE\n## 9.9.9\n>\n\n## 1.0\n")
] == ["1.0"]
assert "<![A-Z]" in PREVIEW.read_text(encoding = "utf-8")
def test_link_resolver_reads_html_containers_the_way_the_others_do():
"""The link resolver must share the parser's HTML block rules, or links in containers go unresolved."""
links = LINKS.read_text(encoding = "utf-8")
for source in (PREVIEW, LINKS):
text = source.read_text(encoding = "utf-8")
assert "HTML_BLOCK_TAGS" in text and "HTML_TAG_ONLY_LINE" in text
assert "inHtmlBlock = !!container.trim()" in links
# Type 7 cannot interrupt a paragraph, so prose above it keeps its links.
assert "return !afterParagraph && HTML_TAG_ONLY_LINE.test(line);" in links
def test_an_escaped_mark_makes_an_image_a_link():
"""`\\` renders as a link, so it resolves to the blob host."""
links = LINKS.read_text(encoding = "utf-8")
assert 'const image = bang === "!" && !isEscaped(line, offset);' in links
assert "isEscaped(line, match.index)" in links
def test_only_markdown_line_endings_split_the_changelog(notes_module):
"""str.splitlines also breaks on U+2028, U+2029, NEL, vertical tab and form feed, which do not
end a CommonMark line; one in prose indexed a release the renderer never shows."""
text = "## 2.0\n\nnote with a separator
## 9.9.9\n\n## 1.0\n\n- old\n"
assert [e.version for e in parse_sections(notes_module, text)] == ["2.0", "1.0"]
entry = find_section(notes_module, text, "2.0")
assert entry is not None and "9.9.9" in entry.body
for separator in ("
", "\x85", "\x0b", "\x0c"):
broken = f"## 2.0\n\nnote{separator}## 9.9.9\n\n## 1.0\n\n- old\n"
assert [e.version for e in parse_sections(notes_module, broken)] == ["2.0", "1.0"]
for ending in ("\n", "\r\n", "\r"):
real = f"## 2.0{ending}{ending}- new{ending}{ending}## 1.0{ending}{ending}- old{ending}"
assert [e.version for e in parse_sections(notes_module, real)] == ["2.0", "1.0"]
def test_link_resolver_reads_comments_before_fences():
"""A fence delimiter inside an HTML comment is not a fence, and a comment opener inside a real
fence is not a comment; the read order matters both ways."""
links = LINKS.read_text(encoding = "utf-8")
# Fence state is read before comments are masked, the order the collapsed preview uses.
assert "const fenceSource = inComment\n ? null\n : FENCE.exec(" in links
# Masking happens only after the in-fence early return.
fence_return = links.index("// Fenced content is literal")
assert links.index("const [line, stillInComment, stillRunOn] = maskComments(") > fence_return
assert "const spans = [...codeSpans(masked), ...comments].sort(" in links
def test_preview_heading_and_quote_markers_follow_the_backend_rule():
"""An ATX heading needs an ASCII space, tab or line end after the marker;
`\\s` also matches a non-breaking space, so prose was read as a heading and
dropped. A blockquote marker takes at most three leading spaces, or an
indented sample holding "> - sample output" sheds its indent into the
summary."""
src = PREVIEW.read_text(encoding = "utf-8")
assert "const HEADING = /^#{1,6}(?:[ \\t]|$)/;" in src
assert "const HEADING_LINE = /^ {0,3}#{1,6}(?:[ \\t]|$)/;" in src
assert "const BLOCKQUOTE = /^ {0,3}>[ \\t]?/;" in src
backend = MODULE.read_text(encoding = "utf-8")
assert "^ {0,3}(?P<hashes>#{1,6})(?:[ \\t]+(?P<title>.*?))?[ \\t]*$" in backend
def test_preview_collects_labels_only_from_real_definitions():
"""Definition-shaped lines in indented code or deep fences are literal, so the label pre-scan
skips the code the collector skips; real definitions indent at most three spaces."""
src = PREVIEW.read_text(encoding = "utf-8")
scan = src.index("const labels = new Set<string>();")
collect = src.index("let deepFence: string | null = null;")
prescan = " ".join(src[scan:collect].split())
assert "let labelFence: string | null = null;" in prescan
assert "if (line.indent - line.column >= INDENTED_CODE_INDENT) { continue; }" in prescan
assert "endsDeepFence(labelFence, labelColumn, line)" in prescan
def test_an_html_block_to_the_left_of_a_list_item_closes_it(notes_module):
"""Types 1 to 6 interrupt a paragraph, so an unindented <div> after "- item"
closes the item and a shallowly indented "## 2.0" below it is a real heading.
Read as a lazy continuation, the item stayed open and swallowed it."""
text = "## 3.0\n\n- item\n<div>\nhidden\n</div>\n\n ## 2.0\n\n- two\n\n## 1.0\n\n- one\n"
assert [e.version for e in parse_sections(notes_module, text)] == ["3.0", "2.0", "1.0"]
nested = "## 3.0\n\n- item\n\n ## 2.0\n\n- two\n\n## 1.0\n\n- one\n"
assert [e.version for e in parse_sections(notes_module, nested)] == ["3.0", "1.0"]
lazy = "## 3.0\n\n- item\ncontinued\n\n ## 2.0\n\n## 1.0\n\n- one\n"
assert [e.version for e in parse_sections(notes_module, lazy)] == ["3.0", "1.0"]
def test_the_download_panel_can_shrink_inside_the_capped_stack():
"""The stack is capped to the viewport and a flex item defaults to min-height:auto, so the
wrapper must set min-h-0 to shrink; only the shared-stack branch needs it."""
panel = (FRONTEND / "features/hub/download-manager/download-manager-panel.tsx").read_text(
encoding = "utf-8"
)
assert 'positioned ? "fixed bottom-4 right-4 z-50" : "flex min-h-0 justify-end"' in panel
provider = (FRONTEND / "app/provider.tsx").read_text(encoding = "utf-8")
stacks = provider.count("zIndex: Z_LAYER.OVERLAY_STACK")
assert _capped_rails(provider) == stacks, "the cap this has to absorb"
@pytest.fixture(scope = "module")
def run_scanner(tmp_path_factory):
"""Runs the frontend markdown scanners under node, since only a real run shows how a CommonMark
renderer classifies a line; @/lib resolves through Vite, not node, so the copies are
rewritten."""
node = shutil.which("node")
if node is None:
pytest.skip("node is needed to run the TypeScript scanners")
work = tmp_path_factory.mktemp("release-notes-scanners")
for source in (PREVIEW, CODE_SPANS, LINKS, LIST_COLUMNS, INLINE_COMMENTS):
rewritten = _TS_ALIAS.sub(r'"./\1.ts"', source.read_text(encoding = "utf-8"))
(work / source.name).write_text(rewritten, encoding = "utf-8")
(work / "run.ts").write_text(_TS_RUNNER, encoding = "utf-8")
def run(kind: str, markdown: str):
result = subprocess.run(
[node, "--experimental-strip-types", "--no-warnings", str(work / "run.ts"), kind],
input = markdown,
capture_output = True,
text = True,
)
if result.returncode != 0:
pytest.skip(f"node could not run the scanners: {result.stderr.strip()[:200]}")
return json.loads(result.stdout)
return run
def preview_leads(preview) -> list[str]:
return [item["lead"] for item in preview["items"]]
def test_a_link_indented_under_a_bullet_still_resolves(run_scanner):
"""CommonMark measures indentation from the container (spec 0.31.2 section 5.2); measuring from
the margin read such a link as code (section 4.4), leaving it relative to Unsloth's origin."""
resolved = run_scanner("links", "- Details:\n\n [guide](docs/a.md)\n")
assert "https://github.com/unslothai/unsloth/blob/main/docs/a.md" in resolved
code = run_scanner("links", "- Added.\n\n [guide](docs/a.md)\n")
assert "[guide](docs/a.md)" in code and "github.com" not in code
top = run_scanner("links", "Intro.\n\n [guide](docs/a.md)\n")
assert "[guide](docs/a.md)" in top and "github.com" not in top
def test_an_indented_fence_does_not_swallow_the_bullets_below_it(run_scanner):
"""A four-space line at document level is indented code, and a top-level
bullet does not continue it. Promoting it to a list-contained fence left a
block open with no closer, so every bullet after it was skipped."""
swallowed = "Example:\n\n ```\n\n- Added the exporter\n- Fixed the crash\n"
assert preview_leads(run_scanner("preview", swallowed)) == [
"Added the exporter",
"Fixed the crash",
]
assert preview_leads(run_scanner("preview", " ```\n\n- Added the exporter\n")) == [
"Added the exporter"
]
nested = "- a\n - b\n ```\n - not a bullet\n ```\n\n- Added tests\n"
assert preview_leads(run_scanner("preview", nested)) == ["a", "Added tests"]
def test_a_table_only_release_previews_as_nothing(run_scanner):
"""A GFM table renders as a grid, so it previews as nothing and the panel
stays collapsed. Falling through to the prose collector put the raw
"| Change | Detail | | --- | --- |" delimiters in the popup instead."""
table = "| Change | Detail |\n| --- | --- |\n| Exporter | Added GGUF |\n"
assert run_scanner("preview", table)["items"] == []
assert preview_leads(run_scanner("preview", f"Some prose.\n\n{table}")) == ["Some prose."]
assert preview_leads(run_scanner("preview", f"{table}- Added tests\n")) == ["Added tests"]
# Mismatched header and delimiter widths are not a table on GitHub, so both lines are prose.
assert preview_leads(run_scanner("preview", "| a | b |\n| --- |\n")) == ["| a | b | | --- |"]
def test_a_fence_inside_a_list_item_ends_with_the_item(notes_module):
"""A fence is scoped to its container (spec 0.31.2 section 4.5), so with no
closer it ends with the item and a dedented "## 2.0" is a real heading.
Document-wide state kept the block open and hid every release below it."""
text = "## 1.0\n\n- item\n ```\n\n## 2.0\n\n- two\n"
assert [e.version for e in parse_sections(notes_module, text)] == ["1.0", "2.0"]
top = "## 1.0\n\n```\n\n## 2.0\n\n- two\n"
assert [e.version for e in parse_sections(notes_module, top)] == ["1.0"]
closed = "## 1.0\n\n- Run:\n ```bash\n ## 9.9.9\n ```\n\n## 2.0\n\n- two\n"
assert [e.version for e in parse_sections(notes_module, closed)] == ["1.0", "2.0"]
assert find_section(notes_module, text, "2.0").body == "- two"
def test_stripping_comments_stays_linear_in_the_code_spans(notes_module):
"""The comment scanner restarted its code-span search per opener, so N spans cost N squared;
notes are reparsed on every request, so the scan must stay linear."""
# A quarter of the budget form's size: the big leg is the 16_000 it was checked at.
spans = 4_000
assert len("`a` <!--x--> " * (spans * 4)) < notes_module.RELEASES_MAX_BYTES
visible, in_comment = assert_linear(
lambda text: notes_module._strip_comments(text, False, False),
lambda n: "`a` <!--x--> " * n,
"comment stripping",
spans,
)
assert in_comment is False
assert "<!--" not in visible and visible.count("`a`") == spans * 4
def test_the_three_scanners_share_one_list_column_rule():
"""The backend parser and both frontend scanners must classify a line the same way; the frontend
pair shares one module ported from the backend's _open_lists tracker."""
shared = LIST_COLUMNS.read_text(encoding = "utf-8")
assert "export function openLists(" in shared
assert "_open_lists" in shared, "the backend function this mirrors"
for source in (PREVIEW, LINKS):
src = source.read_text(encoding = "utf-8")
assert 'from "@/lib/markdown-list-columns"' in src
assert "openLists(" in src
backend = MODULE.read_text(encoding = "utf-8")
assert "_indent_width(visible) - column >= 4" in backend
assert "indentWidth(structure) - column >= INDENTED_CODE_INDENT" in LINKS.read_text(
encoding = "utf-8"
)
def test_a_failed_fetch_keeps_retry_reachable():
"""A release with no notes is ready and a failed fetch is error; only the
error is retryable, and rendering there would replace the Retry button."""
src = " ".join(PANEL.read_text(encoding = "utf-8").split())
assert "const source = notes?.matched ? notes.markdown : null;" in src
# Only NotesStatus renders retry, in the else of the markdown branch: an error has no markdown.
assert "{markdown ? (" in src
assert "retry={retry}" in src
hook = " ".join(
(FRONTEND / "hooks" / "use-release-notes.ts").read_text(encoding = "utf-8").split()
)
assert (
"const failed = !next || (!next.matched && next.error !== null);" in hook
), "the distinction this relies on"
def test_an_unclosed_comment_in_prose_cannot_hide_later_links(run_scanner):
"""CommonMark opens an HTML block (spec 0.31.2 section 4.6, type 2) only when a line begins with
an HTML comment opener; mid-sentence it is inline and must not hide later links."""
repo = "https://github.com/unslothai/unsloth/blob/main/docs/a.md"
item = run_scanner("links", "- Type <!-- to begin a comment\n- See [docs](docs/a.md)\n")
assert repo in item
paragraph = run_scanner("links", "Type <!-- to begin\n\nSee [docs](docs/a.md)\n")
assert repo in paragraph
spanned = run_scanner("links", "- Wrap in `<!--` and `-->`\n- See [docs](docs/a.md)\n")
assert repo in spanned
block = run_scanner("links", "<!-- staged\n- See [docs](docs/a.md)\n-->\n")
assert repo not in block
closer = run_scanner("links", "<!-- staged\n--> See [docs](docs/a.md)\n")
assert repo not in closer
def test_a_bare_level_two_marker_ends_the_release(notes_module, run_scanner):
"""A bare ## line is an empty ATX heading (spec 0.31.2 section 4.2) that ends the release;
requiring whitespace after the marker kept the content below inside it."""
text = "## 2.0\n\n- new thing\n\n##\n\n- SECRET: not part of 2.0\n"
entry = find_section(notes_module, text, "2.0")
assert "new thing" in entry.body
assert "SECRET" not in entry.body
assert [e.version for e in parse_sections(notes_module, text)] == ["2.0"]
prose = "## 2.0\n\n- new thing\n\n##x\n\n- still 2.0\n"
assert "still 2.0" in find_section(notes_module, prose, "2.0").body
preview = run_scanner("preview", "- new thing\n##\nUnrelated scratch notes\n")
assert preview_leads(preview) == ["new thing"]
def test_a_comment_between_bullets_closes_the_list(notes_module, run_scanner):
"""A comment at the margin is an HTML block (spec 0.31.2 section 4.6, type 2) that closes the
list; blanking it as a blank line left the item open and the heading looking nested."""
text = "## 1.0\n\n- old item\n<!-- separator -->\n ## 2.0\n\n- new item\n"
assert [e.version for e in parse_sections(notes_module, text)] == ["1.0", "2.0"]
assert "new item" not in find_section(notes_module, text, "1.0").body
assert "new item" in find_section(notes_module, text, "2.0").body
nested = "## 1.0\n\n- old item\n <!-- separator -->\n ## 2.0\n\n- new item\n"
assert [e.version for e in parse_sections(notes_module, nested)] == ["1.0"]
code = run_scanner("links", "- old item\n<!-- separator -->\n [guide](docs/a.md)\n")
assert "[guide](docs/a.md)" in code and "github.com" not in code
prose = run_scanner("links", "- old item\n <!-- separator -->\n [guide](docs/a.md)\n")
assert "https://github.com/unslothai/unsloth/blob/main/docs/a.md" in prose
preview = run_scanner(
"preview",
"- Details:\n<!-- separator -->\n ```\n - hidden sample\n- Real second item\n",
)
assert preview_leads(preview) == ["Details:", "Real second item"]
def test_a_parenthesised_link_destination_still_resolves(run_scanner):
"""A destination may hold parentheses while they balance (spec 0.31.2 section
6.3), so `[x]((draft).md)` points at `(draft).md`. Stopping at the first
paren matched an empty destination and left the link relative."""
leading = run_scanner("links", "[details]((draft).md)\n")
assert "https://github.com/unslothai/unsloth/blob/main/(draft).md" in leading
image = run_scanner("links", ".png)\n")
assert "https://raw.githubusercontent.com/unslothai/unsloth/main/(badge).png" in image
middle = run_scanner("links", "[api](docs/(v2)/api.md)\n")
assert "https://github.com/unslothai/unsloth/blob/main/docs/(v2)/api.md" in middle
unbalanced = run_scanner("links", "[x](a(b.md)\n")
assert unbalanced == "[x](a(b.md)\n"
closed = run_scanner("links", "[x](a(b.md))\n")
assert "https://github.com/unslothai/unsloth/blob/main/a(b.md)" in closed
nested = run_scanner("links", "[x](((draft)).md)\n")
assert "https://github.com/unslothai/unsloth/blob/main/((draft)).md" in nested
deep = run_scanner("links", ")))).png)\n")
assert "https://raw.githubusercontent.com/unslothai/unsloth/main/((((v2))))" in deep
across = run_scanner("links", "[x](((a).md\n[y](docs/y.md)\n")
assert "https://github.com/unslothai/unsloth/blob/main/docs/y.md" in across
assert "[x](((a).md" in across
def test_a_fence_inside_a_container_still_hides_its_sample(run_scanner):
"""A fence is measured from its container (spec 0.31.2 section 4.5), so a fence in a quote or
under a nested bullet opens; reading only the margin rewrote its links."""
quoted = run_scanner("links", "> ~~~\n> [guide](docs/a.md)\n> ~~~\n")
assert "[guide](docs/a.md)" in quoted and "github.com" not in quoted
nested = run_scanner("links", "- a\n - b\n ~~~\n [x](docs/x.md)\n ~~~\n")
assert "[x](docs/x.md)" in nested and "github.com" not in nested
uneven = run_scanner("links", "> ```\n> [guide](docs/a.md)\n> ````\n")
assert "[guide](docs/a.md)" in uneven and "github.com" not in uneven
left = run_scanner("links", "> ~~~\n[guide](docs/a.md)\n")
assert "https://github.com/unslothai/unsloth/blob/main/docs/a.md" in left
dedented = run_scanner("links", "- a\n ~~~\n[guide](docs/a.md)\n")
assert "https://github.com/unslothai/unsloth/blob/main/docs/a.md" in dedented
document = run_scanner("links", "~~~\n> [guide](docs/a.md)\n~~~\n")
assert "[guide](docs/a.md)" in document and "github.com" not in document
code = run_scanner("links", "- Details:\n\n ~~~\n [guide](docs/a.md)\n")
assert "[guide](docs/a.md)" in code and "github.com" not in code
def test_an_html_block_inside_a_container_is_literal_too(run_scanner):
"""Type 1 and type 6 HTML blocks are measured from their container too, so details and pre
inside a bullet or quote are verbatim; missing them rewrote the literal examples."""
nested = run_scanner("links", "- a\n - b\n <details>\n [x](docs/x.md)\n </details>\n")
assert "[x](docs/x.md)" in nested and "github.com" not in nested
quoted = run_scanner("links", "> <pre>\n> [x](docs/x.md)\n> </pre>\n")
assert "[x](docs/x.md)" in quoted and "github.com" not in quoted
dedented = run_scanner("links", "- a\n - b\n <details>\n[x](docs/x.md)\n")
assert "https://github.com/unslothai/unsloth/blob/main/docs/x.md" in dedented
blank = run_scanner("links", "> <details>\n>\n> [x](docs/x.md)\n")
assert "https://github.com/unslothai/unsloth/blob/main/docs/x.md" in blank
def test_an_underline_left_of_an_item_is_lazy_text_of_it(notes_module, run_scanner):
"""A setext underline may never be a lazy continuation (spec 0.31.2 section
4.3), so `===` left of an open item is more of the item's paragraph.
Rejecting it ended the list and promoted the nested "## 2.0" to a release."""
nested = "## 1.0\n- old note\n===\n ## 2.0\n- new\n"
assert [e.version for e in parse_sections(notes_module, nested)] == ["1.0"]
# A row of dashes is a thematic break, which closes the item.
broken = "## 1.0\n- old note\n---\n ## 2.0\n"
assert [e.version for e in parse_sections(notes_module, broken)] == ["1.0", "2.0"]
apart = "## 1.0\n- old note\n\n===\n ## 2.0\n"
assert [e.version for e in parse_sections(notes_module, apart)] == ["1.0", "2.0"]
resolved = run_scanner("links", "- Details:\n===\n\n [guide](docs/a.md)\n")
assert "https://github.com/unslothai/unsloth/blob/main/docs/a.md" in resolved
def test_a_quote_keeps_its_paragraph_to_itself(notes_module, run_scanner):
"""A marker written outside a blockquote is not text of the quote's
paragraph, so `2. item` under `> quote` opens a list even though an ordered
marker past 1 may not interrupt one (spec 0.31.2 section 5.2). Lending the
paragraph to the document left the list closed and the heading exposed."""
quoted = "## 1.0\n> quote\n2. item\n ## 2.0\n- new\n"
assert [e.version for e in parse_sections(notes_module, quoted)] == ["1.0"]
heading = "## 1.0\n> # inner\n2. item\n ## 2.0\n"
assert [e.version for e in parse_sections(notes_module, heading)] == ["1.0"]
lazy = "## 1.0\n> quote\ntext\n2. item\n ## 2.0\n"
assert [e.version for e in parse_sections(notes_module, lazy)] == ["1.0"]
prose = "## 1.0\nprose\n2. item\n ## 2.0\n"
assert [e.version for e in parse_sections(notes_module, prose)] == ["1.0", "2.0"]
assert preview_leads(run_scanner("preview", "> quote\n2. item\n")) == ["item"]
def test_indented_code_before_an_ordered_marker_still_opens_a_list(notes_module):
"""An indented code block ends at the first line not indented enough, and no
paragraph is open, so `2. item` opens a list whatever its start number.
Reading it as code text left the list closed and the nested heading exposed."""
joined = "## 1.0\n\n code\n2. item\n ## 2.0\n- new\n"
assert [e.version for e in parse_sections(notes_module, joined)] == ["1.0"]
apart = "## 1.0\n\n code\n\n2. item\n ## 2.0\n- new\n"
assert [e.version for e in parse_sections(notes_module, apart)] == ["1.0"]
inside = "## 1.0\n\n code\n - item\n ## 2.0\n"
assert [e.version for e in parse_sections(notes_module, inside)] == ["1.0", "2.0"]
def test_a_fence_written_as_an_item_first_content_opens_in_that_item(run_scanner):
"""A block straight after a list marker is the item's first content, measured from where it
starts (spec 0.31.2 section 5.2), so a fence there opens; reading the whole line missed it."""
sample = run_scanner("links", "- ```md\n [example](docs/a.md)\n ```\n")
assert "[example](docs/a.md)" in sample and "github.com" not in sample
ordered = run_scanner("links", "1. ~~~\n [example](docs/a.md)\n ~~~\n")
assert "[example](docs/a.md)" in ordered and "github.com" not in ordered
preview = run_scanner("preview", "- ```md\n sample text\n ```\n- Added tests\n")
assert preview_leads(preview) == ["Added tests"]
padded = run_scanner("links", "- ```\n [example](docs/a.md)\n")
assert "https://github.com/unslothai/unsloth/blob/main/docs/a.md" in padded
lazy = run_scanner("links", "Intro.\n2. ```\n[guide](docs/a.md)\n")
assert "https://github.com/unslothai/unsloth/blob/main/docs/a.md" in lazy
def test_an_html_block_ends_with_the_item_it_was_written_in(notes_module, run_scanner):
"""An HTML block takes no lazy continuation line, so one opened in an item ends with that item,
as a fence does; ending it only on a blank line swallowed the next release."""
text = "## 1.0\n\n- item\n\n <div>\n## 2.0\n\n- new thing\n"
assert [e.version for e in parse_sections(notes_module, text)] == ["1.0", "2.0"]
assert "new thing" in find_section(notes_module, text, "2.0").body
raw = "## 1.0\n\n- item\n\n <pre>\n## 2.0\n\n- new thing\n"
assert [e.version for e in parse_sections(notes_module, raw)] == ["1.0", "2.0"]
nested = "## 1.0\n\n- item\n\n <div>\n ## 2.0\n"
assert [e.version for e in parse_sections(notes_module, nested)] == ["1.0"]
preview = run_scanner("preview", "- item\n\n <div>\n- Added tests\n")
assert preview_leads(preview) == ["item", "Added tests"]
marked = "## 1.0\n\n- <div>\n## 2.0\n\n- new thing\n"
assert [e.version for e in parse_sections(notes_module, marked)] == ["1.0", "2.0"]
def test_a_comment_may_close_on_a_later_line_of_its_paragraph(run_scanner):
"""A mid-sentence comment belongs to its paragraph, so its closing delimiter may come on a later
line; ending it at its own line let a backtick pair up and hide a link."""
carried = run_scanner("links", "Note <!-- ` open\nstill --> see [d](docs/a.md) and `x`\n")
assert "https://github.com/unslothai/unsloth/blob/main/docs/a.md" in carried
inside = run_scanner("links", "Note <!-- see [c](docs/c.md)\nmore --> end\n")
assert "[c](docs/c.md)" in inside and "github.com" not in inside
preview = run_scanner(
"preview", "- Added X <!-- TODO: rewrite\n this properly -->\n- Second\n"
)
assert preview_leads(preview) == ["Added X", "Second"]
broken = run_scanner("links", "Note <!-- open\n\nsecret --> end [d](docs/a.md)\n")
assert "https://github.com/unslothai/unsloth/blob/main/docs/a.md" in broken
headed = run_scanner("links", "Note <!-- open\n## 2.0 --> end [d](docs/a.md)\n")
assert "https://github.com/unslothai/unsloth/blob/main/docs/a.md" in headed
assert preview_leads(run_scanner("preview", "Note <!-- open\n\n- Second\n")) == ["Second"]
def test_only_punctuation_is_escapable_in_a_link_destination(run_scanner):
"""CommonMark escapes ASCII punctuation and nothing else (spec 0.31.2 section
2.4), so the backslash in `docs\\alpha.md` is a character of the path.
Dropping it rewrote a Windows or namespaced path to the wrong file."""
kept = run_scanner("links", "[guide](docs\\alpha.md)\n")
assert "https://github.com/unslothai/unsloth/blob/main/docs%5Calpha.md" in kept
escaped = run_scanner("links", "[guide](docs\\\\alpha.md)\n")
assert "https://github.com/unslothai/unsloth/blob/main/docs%5Calpha.md" in escaped
paren = run_scanner("links", "[guide](a\\(b.md)\n")
assert "https://github.com/unslothai/unsloth/blob/main/a(b.md" in paren
spaced = run_scanner("links", "[guide](a\\ b.md)\n")
assert spaced == "[guide](a\\ b.md)\n"
def test_one_definition_does_not_hide_the_next(run_scanner):
"""Consecutive link definitions (spec 0.31.2 section 4.7) are not paragraph text, so counting
one as prose left the next unresolved; the backend already reads them this way."""
text = (
"- AMD support is here, see [the AMD guide][amd] and the\n"
" [Intel notes][xpu].\n\n"
"[amd]: docs/basics/amd.md\n"
"[xpu]: docs/basics/xpu.md\n"
)
resolved = run_scanner("links", text)
base = "https://github.com/unslothai/unsloth/blob/main/docs/basics/"
assert f"[amd]: {base}amd.md" in resolved
assert f"[xpu]: {base}xpu.md" in resolved
run = run_scanner("links", "[a]: docs/a.md\n[b]: docs/b.md\n[c]: docs/c.md\n")
assert run.count("https://github.com/unslothai/unsloth/blob/main/docs/") == 3
prose = run_scanner("links", "[a]: docs/a.md\nintro\n[b]: docs/b.md\n")
assert "[b]: docs/b.md" in prose
def test_a_comment_closed_on_its_own_line_still_closes(run_scanner):
"""A multiline comment is often closed on a line of its own, and a wrapped line may open with
emphasis; reading that punctuation as a new block left the note visible."""
closer = run_scanner(
"preview",
"- DoRA training is available in Unsloth. <!-- TODO confirm the exact\n"
" flag name before release\n-->\n",
)
assert preview_leads(closer) == ["DoRA training is available in Unsloth."]
starred = run_scanner(
"preview",
"- DoRA training is available. <!-- TODO confirm the\n *before* release -->\n",
)
assert preview_leads(starred) == ["DoRA training is available."]
underscored = run_scanner(
"preview",
"- DoRA training is available. <!-- TODO confirm the\n _draft_ note -->\n",
)
assert preview_leads(underscored) == ["DoRA training is available."]
broken = run_scanner("links", "Note <!-- open\n## 2.0\nsecret --> [d](docs/a.md)\n")
assert "https://github.com/unslothai/unsloth/blob/main/docs/a.md" in broken
item = run_scanner("links", "Note <!-- open\n- bullet\nsecret --> [d](docs/a.md)\n")
assert "https://github.com/unslothai/unsloth/blob/main/docs/a.md" in item
def test_a_comment_written_as_an_item_first_content_is_a_block(notes_module, run_scanner):
"""A comment as an item's first content is an HTML block inside that item (spec 0.31.2 section
4.6, type 2); finding its opener only at the margin let a marker before it hide the block."""
item = run_scanner("links", "- <!-- new --> AMD support, see [the guide](docs/amd.md)\n")
assert item == "- <!-- new --> AMD support, see [the guide](docs/amd.md)\n"
for text in (
"* <!-- new --> see [the guide](docs/amd.md)\n",
"1. <!-- new --> see [the guide](docs/amd.md)\n",
"- outer\n - <!-- new --> see [the guide](docs/amd.md)\n",
):
assert "github.com" not in run_scanner("links", text)
multiline = run_scanner("links", "- <!-- hidden\n [a](docs/x.md)\n -->\n")
assert "[a](docs/x.md)" in multiline and "github.com" not in multiline
dedented = run_scanner("links", "- <!-- hidden\n[a](docs/x.md)\n")
assert "https://github.com/unslothai/unsloth/blob/main/docs/x.md" in dedented
preview = run_scanner("preview", "- <!-- new --> hidden note\n- Real bullet\n")
assert preview_leads(preview) == ["Real bullet"]
text = "## 1.0\n\n- <!-- hidden\n\n ## 2.0\n"
assert [e.version for e in parse_sections(notes_module, text)] == ["1.0"]
@pytest.mark.parametrize(
"tag,kept,dropped",
[
(
"v0.1.60-beta",
["Meta has released Muse Glimmer", "[Run Muse Glimmer]"],
[
"## Updating / installing Unsloth",
"install.sh",
"## What's Changed",
"## New Contributors",
"Full Changelog",
],
),
(
# The install block sits between content sections; cutting there loses the Keyv notice.
"v0.1.526-beta",
[
"## August 7th Update",
"## DeepSeek V4 Flash 0731 + DSpark",
"## Kimi K3",
"Keyv security incident",
],
["## Updating / installing Unsloth", "install.ps1", "## What's Changed"],
),
(
"v0.1.501-beta",
[
"## 23rd July Update",
"## Train LLMs Locally on AMD",
"### Safer Agents",
],
[
"## Updating / installing Unsloth",
"## What's Changed in Unsloth",
"## What's Changed in Unsloth-Zoo",
"## 23rd July Update Unsloth changelog",
],
),
(
# The install block's platform headings are siblings, so level alone does not end it.
"v0.1.43-beta",
["## Mac Updates", "## Windows Updates", "## Blackwell GPUs Update"],
[
"To update Unsloth or install a new Unsloth Studio",
"### macOS, Linux, WSL:",
"### Windows:",
"irm https://unsloth.ai/install.ps1",
],
),
(
# All level 3; the install block is introduced by a paragraph, not a heading.
"v0.1.471-beta",
["### Better context length algorithm", "### Training & General Fixes"],
[
"## What's Changed",
"## New Contributors",
"To update Unsloth or install a new Unsloth Studio",
"Ensure your version is",
"curl -fsSL https://unsloth.ai/install.sh",
"irm https://unsloth.ai/install.ps1",
],
),
],
)
def test_real_release_bodies_keep_their_announcement(notes_module, tag, kept, dropped):
body = (BODIES / f"{tag}.md").read_text(encoding = "utf-8")
stripped = notes_module.strip_release_body(body)
for text in kept:
assert text in stripped, f"{tag} lost {text!r}"
for text in dropped:
assert text not in stripped, f"{tag} kept {text!r}"
def test_the_build_provenance_the_workflow_appends_is_dropped(notes_module):
"""release-desktop.yml appends this block, so it arrives under announcements."""
body = "The announcement.\n\n### Build provenance\n\n- workflow run 123\n"
stripped = notes_module.strip_release_body(body)
assert stripped == "The announcement."
def test_a_generated_heading_inside_a_sample_is_not_one(notes_module):
"""A release documenting the notes format writes `## What's Changed` in a
fence, and reading it as the footer would cut the announcement there."""
body = (
"The announcement.\n\n"
"```md\n## What's Changed\n```\n\n"
"## Kimi K3\n\n- still here\n\n"
"## What's Changed\n\n* a pull request\n"
)
stripped = notes_module.strip_release_body(body)
assert "```md" in stripped and "## Kimi K3" in stripped and "still here" in stripped
assert "a pull request" not in stripped
def test_a_heading_that_only_reads_like_boilerplate_is_kept(notes_module):
"""A reviewed list, not a substring sweep: these titles only share words."""
for title in (
"## What changed in Gemma 4",
"## Updating models is now 2x faster",
"## Installing a LoRA from the Hub",
):
body = f"Intro.\n\n{title}\n\n- a real change\n"
assert "a real change" in notes_module.strip_release_body(body), title
def test_an_install_block_introduced_by_a_paragraph_is_dropped(notes_module):
"""`v0.1.471-beta` writes the install sentence with no hashes. A paragraph
has no level, so its block runs to the next non-platform heading."""
body = (
"The announcement.\n\n"
"To update Unsloth or install a new Unsloth Studio, you must use the below.\n"
"Ensure your version is `2026.6.9` for the latest.\n\n"
"MacOS, Linux, WSL:\n```\ncurl -fsSL https://unsloth.ai/install.sh | sh\n```\n\n"
"Windows:\n```\nirm https://unsloth.ai/install.ps1 | iex\n```\n\n"
"### Better context length algorithm\n\n- a real change\n"
)
stripped = notes_module.strip_release_body(body)
assert stripped == (
"The announcement.\n\n### Better context length algorithm\n\n- a real change"
)
def test_a_paragraph_install_block_keeps_its_platform_headings(notes_module):
"""Platform headings go with the block whether it opened as heading or prose."""
body = (
"Intro.\n\n"
"To update Unsloth, use the commands below:\n\n"
"#### macOS, Linux, WSL:\n```\ncurl -fsSL https://unsloth.ai/install.sh | sh\n```\n\n"
"#### Windows:\n```\nirm https://unsloth.ai/install.ps1 | iex\n```\n\n"
"## Fixes\n\n1. a real fix\n"
)
stripped = notes_module.strip_release_body(body)
assert stripped == "Intro.\n\n## Fixes\n\n1. a real fix"
def test_a_platform_heading_opens_an_install_block_on_its_own(notes_module):
"""v0.1.0-beta and v0.1.41-beta head commands with a bare platform heading, so no Updating line
may be required; all seven platform headings in the bodies open a block."""
body = (
"Intro.\n\n"
"#### macOS, Linux, WSL:\n```\ncurl -fsSL https://unsloth.ai/install.sh | sh\n```\n\n"
"#### Windows:\n```\nirm https://unsloth.ai/install.ps1 | iex\n```\n\n"
"## Fixes\n\n1. a real fix\n"
)
stripped = notes_module.strip_release_body(body)
assert stripped == "Intro.\n\n## Fixes\n\n1. a real fix"
def test_only_a_paragraph_of_its_own_opens_an_install_block(notes_module):
"""The same words inside the announcement are prose, not instructions:
`v0.1.39-beta` says "call `curl ...` to update" mid-sentence, and generated
entries are `* Update ...` lines. Neither opens a document-level paragraph."""
continuation = (
"Unsloth Studio 2026.5.2 is out.\n"
"To update Unsloth, run the installer.\n\n"
"## Fixes\n\n- a real fix\n"
)
stripped = notes_module.strip_release_body(continuation)
assert "Unsloth Studio 2026.5.2 is out." in stripped
assert "To update Unsloth, run the installer." in stripped
assert "- a real fix" in stripped
for line in ("* Update Unsloth icons by @someone", "> To update Unsloth, run it"):
body = f"Intro.\n\n{line}\n\n## Fixes\n\n- a real fix\n"
assert "a real fix" in notes_module.strip_release_body(body), line
def test_a_paragraph_install_block_does_not_swallow_deeper_headings(notes_module):
"""A heading section drops its subheadings, but a paragraph has no level, so
the next heading resumes the announcement whatever its depth."""
body = (
"Intro.\n\n"
"To update Unsloth, use the command below:\n"
"```\ncurl -fsSL https://unsloth.ai/install.sh | sh\n```\n\n"
"###### Deeply nested announcement\n\n- a real change\n"
)
stripped = notes_module.strip_release_body(body)
assert stripped == "Intro.\n\n###### Deeply nested announcement\n\n- a real change"
@pytest.fixture(autouse = True)
def github_lockout(notes_module):
from utils.prebuilt import freshness_flow
freshness_flow._api_rate_limited_until = 0.0
notes_module.reset_release_notes_cache()
yield freshness_flow
freshness_flow._api_rate_limited_until = 0.0
notes_module.reset_release_notes_cache()
@pytest.mark.parametrize(
("url_override", "env", "expected"),
[
(None, {"GH_TOKEN": "ghp_gh", "GITHUB_TOKEN": "ghp_github"}, "Bearer ghp_github"),
(None, {"GH_TOKEN": "ghp_gh"}, "Bearer ghp_gh"),
("https://mirror.example/releases", {"GH_TOKEN": "ghp_gh"}, None),
("http://api.github.com/repos/x/releases", {"GITHUB_TOKEN": "ghp_secret"}, None),
],
)
def test_where_the_release_notes_token_may_travel(
notes_module, github_lockout, monkeypatch, url_override, env, expected
):
import urllib.error
seen = []
def capture(request, timeout = None):
seen.append(request)
raise urllib.error.URLError("offline")
monkeypatch.setattr(notes_module.urllib.request, "urlopen", capture)
for name in ("GH_TOKEN", "GITHUB_TOKEN"):
monkeypatch.delenv(name, raising = False)
for name, value in env.items():
monkeypatch.setenv(name, value)
if url_override is None:
monkeypatch.delenv(notes_module.RELEASES_URL_ENV_VAR, raising = False)
else:
monkeypatch.setenv(notes_module.RELEASES_URL_ENV_VAR, url_override)
notes_module._fetch_latest_release()
assert seen[0].get_header("Authorization") == expected
assert "Authorization" not in seen[0].headers
@pytest.mark.parametrize(
("url_override", "status", "remaining", "body", "shared", "reported"),
[
(None, 403, "0", b"", True, True),
(None, 429, "4998", b"", True, True),
(None, 403, "4998", b'{"message": "secondary rate limit"}', True, True),
(None, 403, "4998", b"", False, False),
("https://mirror.example/releases", 429, "0", b"", False, True),
],
)
def test_which_release_note_refusals_reach_the_shared_lockout(
notes_module,
github_lockout,
monkeypatch,
url_override,
status,
remaining,
body,
shared,
reported,
):
import email.message
import io
import urllib.error
if url_override is None:
monkeypatch.delenv(notes_module.RELEASES_URL_ENV_VAR, raising = False)
else:
monkeypatch.setenv(notes_module.RELEASES_URL_ENV_VAR, url_override)
headers = email.message.Message()
headers["X-RateLimit-Remaining"] = remaining
headers["X-RateLimit-Reset"] = str(int(time.time() + 1800))
def refuse(request, timeout = None):
raise urllib.error.HTTPError(request.full_url, status, "refused", headers, io.BytesIO(body))
monkeypatch.setattr(notes_module.urllib.request, "urlopen", refuse)
result = notes_module.get_latest_release()
assert (github_lockout.github_rate_limit_remaining() > 0) is shared
assert ("rate limit" in (result.error or "").lower()) is reported
@pytest.mark.parametrize("url_override", [None, "https://mirror.example/releases"])
def test_the_shared_lockout_parks_only_the_github_api(
notes_module, github_lockout, monkeypatch, url_override
):
import urllib.error
if url_override is None:
monkeypatch.delenv(notes_module.RELEASES_URL_ENV_VAR, raising = False)
else:
monkeypatch.setenv(notes_module.RELEASES_URL_ENV_VAR, url_override)
github_lockout.hold_github_api(60)
calls = []
def capture(request, timeout = None):
calls.append(request.full_url)
raise urllib.error.URLError("offline")
monkeypatch.setattr(notes_module.urllib.request, "urlopen", capture)
notes_module.get_latest_release(refresh = True)
assert calls == ([] if url_override is None else [url_override])