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. See /studio/LICENSE.AGPL-3.0
"""Regression tests for unsloth_cli.commands.export: pin the CLI to the export_* 3-tuple contract (was unpacking 2, crashing every `unsloth export`) via a fake ExportBackend in sys.modules."""
from __future__ import annotations
import importlib
import sys
import types
from pathlib import Path
import pytest
import typer
from typer.testing import CliRunner
class _FakeExportBackend:
"""Stand-in for ExportBackend: export_* return the 3-tuple, load_checkpoint stays a 2-tuple."""
last_call: dict = {}
last_load: dict = {}
def __init__(self) -> None:
self.loaded: str | None = None
def load_checkpoint(self, **kwargs):
_FakeExportBackend.last_load = dict(kwargs)
self.loaded = kwargs.get("checkpoint_path")
return True, f"Loaded {self.loaded}"
def scan_checkpoints(self, **kwargs):
return []
def export_merged_model(self, **kwargs):
_FakeExportBackend.last_call = {"method": "export_merged_model", "kwargs": kwargs}
return True, "merged ok", str(Path(kwargs["save_directory"]).resolve())
def export_base_model(self, **kwargs):
_FakeExportBackend.last_call = {"method": "export_base_model", "kwargs": kwargs}
return True, "base ok", str(Path(kwargs["save_directory"]).resolve())
def export_gguf(self, **kwargs):
_FakeExportBackend.last_call = {"method": "export_gguf", "kwargs": kwargs}
return True, "gguf ok", str(Path(kwargs["save_directory"]).resolve())
def export_lora_adapter(self, **kwargs):
_FakeExportBackend.last_call = {"method": "export_lora_adapter", "kwargs": kwargs}
return True, "lora ok", str(Path(kwargs["save_directory"]).resolve())
def _install_fake_studio_backend(monkeypatch: pytest.MonkeyPatch) -> None:
"""Inject a fake studio.backend.core.export into sys.modules so the CLI's lazy import binds to it; parent packages stubbed to skip the structlog-dependent tree."""
# The CLI puts studio/backend on sys.path, whose tests/ package then shadows the repo's for any
# process spawned later in this worker (`No module named 'tests.<file>'`): restore it afterwards.
monkeypatch.setattr(sys, "path", list(sys.path))
# Load the real CLI first: the stubs below shadow studio.backend.utils, which it imports.
importlib.import_module("unsloth_cli.commands.export")
for name in ("studio", "studio.backend", "studio.backend.core"):
monkeypatch.setitem(sys.modules, name, types.ModuleType(name))
fake_mod = types.ModuleType("studio.backend.core.export")
fake_mod.ExportBackend = _FakeExportBackend
monkeypatch.setitem(sys.modules, "studio.backend.core.export", fake_mod)
monkeypatch.delitem(sys.modules, "unsloth_cli.commands.export", raising = False)
@pytest.fixture
def cli_app(monkeypatch: pytest.MonkeyPatch) -> typer.Typer:
"""Typer app wrapping unsloth_cli.commands.export.export."""
_FakeExportBackend.last_call = {}
_FakeExportBackend.last_load = {}
_install_fake_studio_backend(monkeypatch)
from unsloth_cli.commands import export as export_cmd
app = typer.Typer()
app.command("export")(export_cmd.export)
# Typer flattens a single-command app; a second command keeps "export" a real subcommand.
@app.command("noop")
def _noop() -> None: # pragma: no cover - only exists to pin routing
pass
return app
@pytest.fixture
def runner() -> CliRunner:
return CliRunner()
def test_an_export_run_leaves_sys_path_as_it_found_it(runner: CliRunner, tmp_path: Path) -> None:
"""The run puts studio/backend first on sys.path, and studio/backend/tests is a package: left
there, every later `spawn` child in the worker resolves `tests.<file>` to it and dies. First in
the file, so the tests below cannot have leaked the path before it looks."""
before = list(sys.path)
ckpt = tmp_path / "ckpt"
ckpt.mkdir()
backend_dir = str(Path(__file__).resolve().parents[1] / "studio" / "backend")
with pytest.MonkeyPatch.context() as monkeypatch:
_install_fake_studio_backend(monkeypatch)
# Another collected module may already have put it there, and the CLI skips a path it finds.
# In place, on the copy the helper above swapped in: only that helper's restore may undo it.
sys.path[:] = [p for p in sys.path if p != backend_dir]
clean = list(sys.path)
from unsloth_cli.commands import export as export_cmd
app = typer.Typer()
app.command("export")(export_cmd.export)
app.command("noop")(lambda: None)
result = runner.invoke(
app, ["export", str(ckpt), str(tmp_path / "out"), "--format", "lora"]
)
assert result.exit_code == 0, result.output
# Non-vacuous: the run did put studio/backend on sys.path, which the restore has to undo.
assert backend_dir in sys.path and backend_dir not in clean
assert sys.path == before
@pytest.mark.parametrize(
"format_flag,quant_flag",
[
("merged-16bit", None),
("merged-4bit", None),
("gguf", "q4_k_m"),
("lora", None),
],
)
def test_cli_export_unpacks_three_tuple(
cli_app: typer.Typer,
runner: CliRunner,
tmp_path: Path,
format_flag: str,
quant_flag: str | None,
) -> None:
"""Each --format path unpacks the 3-tuple without ValueError (pre-fix: 'too many values to unpack (expected 2)')."""
ckpt = tmp_path / "ckpt"
ckpt.mkdir()
out = tmp_path / "out"
cli_args = ["export", str(ckpt), str(out), "--format", format_flag]
if quant_flag is not None:
cli_args += ["--quantization", quant_flag]
result = runner.invoke(cli_app, cli_args)
assert result.exit_code == 0, (
f"CLI exited with code {result.exit_code} for --format {format_flag}.\n"
f"Output:\n{result.output}\n"
f"Exception: {result.exception!r}"
)
expected_prefix = format_flag.split("-")[0]
assert f"{expected_prefix} ok" in result.output
@pytest.mark.parametrize(
"format_flag,quant_flag,expected_method",
[
("merged-16bit", None, "export_merged_model"),
("merged-4bit", None, "export_merged_model"),
("gguf", "q4_k_m", "export_gguf"),
("lora", None, "export_lora_adapter"),
],
)
def test_cli_export_forwards_private_flag(
cli_app: typer.Typer,
runner: CliRunner,
tmp_path: Path,
format_flag: str,
quant_flag: str | None,
expected_method: str,
) -> None:
"""--private flag is forwarded as private=True to backend.export_* for every format."""
ckpt = tmp_path / "ckpt"
ckpt.mkdir()
out = tmp_path / "out"
cli_args = [
"export",
str(ckpt),
str(out),
"--format",
format_flag,
"--push-to-hub",
"--repo-id",
"test/repo",
"--private",
]
if quant_flag is not None:
cli_args += ["--quantization", quant_flag]
result = runner.invoke(cli_app, cli_args)
assert result.exit_code == 0, f"CLI error:\n{result.output}"
assert _FakeExportBackend.last_call.get("method") == expected_method
assert _FakeExportBackend.last_call.get("kwargs", {}).get("private") is True
def test_cli_export_forwards_hf_token_to_checkpoint_load(
cli_app: typer.Typer, runner: CliRunner, tmp_path: Path
) -> None:
"""--hf-token reaches load_checkpoint, not just the Hub push."""
ckpt = tmp_path / "ckpt"
ckpt.mkdir()
out = tmp_path / "out"
result = runner.invoke(
cli_app,
["export", str(ckpt), str(out), "--hf-token", "hf_cli_token"],
)
assert result.exit_code == 0, f"CLI error:\n{result.output}"
assert _FakeExportBackend.last_load.get("hf_token") == "hf_cli_token"