Skip to content
Merged
4 changes: 4 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,10 @@ A comment says what the code does and why, in one or two sentences. Change histo

Framework code raises a `VipError` subclass (`src/vip/errors.py`) instead of calling `sys.exit`. `src/vip/cli/app.py`'s `except VipError` handler is the single top-level place that maps an error to a process exit code. Test steps and assertions under `src/vip_tests/` don't catch `VipError`; if a client call raises one, let it propagate so the test fails with the real cause instead of a laundered message (see docs/test-architecture.md's "Fail, warn, or skip" section). The exception is best-effort teardown: the end-of-run Connect sweep in `src/vip_tests/conftest.py` catches `ProductUnreachableError` and logs it, so a failed cleanup can't turn a green run red. A broad `except Exception` is allowed only where an exception is genuinely tolerated (not translated into a more specific error and re-raised) -- mark it `# noqa: BLE001` and add a comment naming what is being tolerated and why, the way `src/vip/workbench_ui.py` does at each of its blind excepts.

## Output

Never call `print()` (ruff `T201` enforces it); write through `src/vip/output.py`. `out()` is for command results a caller might pipe (report path, install plan, status table, JSON, version) and goes to stdout; `info()` (progress), `warn()`, `error()` and `debug()` (diagnostics) go to stderr. Pass the message exactly as it should appear: the module adds no prefix, so `>>> ` stays in the caller's string. The level is `quiet` (hides `info`), `normal`, or `verbose` (adds `debug`); `vip -q` / `vip -v` set it before the subcommand runs (`vip verify --verbose` still means full tracebacks and also enables `debug`, unless `-q` is given, which always wins). `VIP_VERBOSITY=quiet|normal|verbose` carries the level into the pytest subprocess that `vip verify` starts, so code under `vip.auth` and `vip.plugin` honours it, and the `vip_verbose` fixture is `False` under quiet even with `--vip-verbose`. `vip.*` `logging` records reach stderr through `output.configure_logging()`, which the CLI entry point calls once and `plugin/configure.py::pytest_configure` calls with `propagate=True` in the pytest subprocess and each xdist worker, so pytest's log capture still sees them. Selftests assert on `capsys.readouterr().out` or `.err` to match the stream; a test that needs `debug` output calls `set_verbosity(Verbosity.VERBOSE)`.

## Testing

There are two distinct test suites:
Expand Down
4 changes: 3 additions & 1 deletion docs/development.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,9 @@ uv run --extra dev ruff format . # reformat
```

Ruff's rule set is the `select` list in `pyproject.toml` under
`[tool.ruff.lint]`; line length is 100.
`[tool.ruff.lint]`; line length is 100. The set includes `T201`, so `print()` is a
lint error: write through `vip.output` instead (`out()` for stdout results,
`info()`/`warn()`/`error()`/`debug()` for stderr; see "Output" in `AGENTS.md`).

### Pre-commit hooks (optional)

Expand Down
6 changes: 4 additions & 2 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -252,7 +252,7 @@ src = ["src", "selftests", "examples"]
# PLW1514 is preview-only; explicit-preview-rules keeps every other preview rule off.
preview = true
explicit-preview-rules = true
select = ["ARG001", "ARG002", "ARG005", "B", "BLE", "C4", "D101", "D102", "D103", "D202", "D209", "D210", "D403", "D413", "E", "F", "I", "ISC", "N", "PERF", "PGH", "PIE", "PLC0207", "PLC0415", "PLR0124", "PLR0402", "PLR1711", "PLR5501", "PLW0108", "PLW1510", "PLW1514", "PT", "PTH", "RET", "RUF001", "RUF002", "RUF003", "RUF012", "RUF023", "RUF043", "RUF059", "RUF100", "S101", "SIM", "TID", "UP"]
select = ["ARG001", "ARG002", "ARG005", "B", "BLE", "C4", "D101", "D102", "D103", "D202", "D209", "D210", "D403", "D413", "E", "F", "I", "ISC", "N", "PERF", "PGH", "PIE", "PLC0207", "PLC0415", "PLR0124", "PLR0402", "PLR1711", "PLR5501", "PLW0108", "PLW1510", "PLW1514", "PT", "PTH", "RET", "RUF001", "RUF002", "RUF003", "RUF012", "RUF023", "RUF043", "RUF059", "RUF100", "S101", "SIM", "T201", "TID", "UP"]

# PERF203: per-item try/except in cleanup and probe loops is deliberate (the loop must continue past a failing item), and the per-iteration cost it flags is gone on Python 3.11+.
ignore = [
Expand All @@ -265,4 +265,6 @@ ignore = [
"selftests/**" = ["ARG001", "ARG002", "ARG005", "D101", "D102", "D103", "PLC0415", "S101"]
"src/vip_tests/**" = ["ARG001", "ARG002", "ARG005", "D101", "D102", "D103", "PLC0415", "S101"]
"examples/**" = ["ARG001", "ARG002", "ARG005", "D101", "D102", "D103", "S101"]
"docker/**" = ["ARG001", "ARG002", "ARG005", "S101"]
# T201: standalone scripts that cannot import vip.output; their stdout is read by CI and shell callers.
"docker/**" = ["ARG001", "ARG002", "ARG005", "S101", "T201"]
"scripts/**" = ["T201"]
16 changes: 16 additions & 0 deletions selftests/conftest.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,13 @@

from __future__ import annotations

import logging
from pathlib import Path

import pytest

from vip import output

# Enable the pytester fixture for plugin integration tests.
pytest_plugins = ["pytester"]

Expand All @@ -26,6 +29,19 @@
)


@pytest.fixture(autouse=True)
def _restore_output_state():
"""Undo verbosity and ``vip`` logger changes a selftest (or ``main()``) made."""
level = output.get_verbosity()
logger = logging.getLogger("vip")
handlers, propagate, log_level = list(logger.handlers), logger.propagate, logger.level
yield
output.set_verbosity(level)
logger.handlers[:] = handlers
logger.propagate = propagate
logger.setLevel(log_level)


@pytest.fixture(autouse=True)
def _restore_auth_entrypoints():
"""Undo in-process ``pytester`` runs that rebind ``vip.auth``'s entrypoints.
Expand Down
4 changes: 2 additions & 2 deletions selftests/install/test_playwright.py
Original file line number Diff line number Diff line change
Expand Up @@ -194,7 +194,7 @@ def test_install_chromium_filters_beware_preamble_and_replaces(monkeypatch, caps
assert "officially supported" not in out.out + out.err
assert "downloading fallback build" not in out.out + out.err
assert "Downloading Chromium 120" in out.out
assert "Installed Playwright Chromium" in out.out
assert "Installed Playwright Chromium" in out.err


def test_install_chromium_forwards_normal_output_unchanged(monkeypatch, capsys):
Expand All @@ -208,4 +208,4 @@ def test_install_chromium_forwards_normal_output_unchanged(monkeypatch, capsys):
assert "Downloading Chromium 120" in out.out
assert "Chromium downloaded." in out.out
# No BEWARE means no vip summary line either.
assert "Installed Playwright Chromium" not in out.out
assert "Installed Playwright Chromium" not in out.out + out.err
2 changes: 1 addition & 1 deletion selftests/install/test_runner.py
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,7 @@ def test_execute_install_plan_not_root_message_names_skip_system(monkeypatch, tm
rc = rn.execute_install_plan(plan, manifest=manifest, manifest_path=manifest_path)

assert rc == 2
assert "--skip-system" in capsys.readouterr().out
assert "--skip-system" in capsys.readouterr().err


def test_execute_install_plan_claims_pending(monkeypatch, tmp_path: Path):
Expand Down
14 changes: 7 additions & 7 deletions selftests/test_auth_apikey.py
Original file line number Diff line number Diff line change
Expand Up @@ -567,7 +567,7 @@ def get_side_effect(path, **_kw):
with patcher:
assert _create_api_key_via_session(page, "https://c.example.com", "k") is None

assert "boom" in capsys.readouterr().out
assert "boom" in capsys.readouterr().err

def test_user_endpoint_403_warning_includes_body(self, capsys):
"""When cookie auth is rejected at /v1/user, the response body must
Expand All @@ -588,7 +588,7 @@ def test_user_endpoint_403_warning_includes_body(self, capsys):
with patcher:
assert _create_api_key_via_session(page, "https://c.example.com", "k") is None

out = capsys.readouterr().out
out = capsys.readouterr().err
assert "HTTP 403" in out
assert "CSRF token is required" in out

Expand Down Expand Up @@ -622,7 +622,7 @@ def get_side_effect(path, **_kw):
result = _create_api_key_via_session(page, "https://c.example.com/connect", "k")
assert result is None

out = capsys.readouterr().out
out = capsys.readouterr().err
# Full URL is reported, not just the relative path.
assert "https://c.example.com/connect/__api__/v1/user" in out
# Content-Type appears so users can spot Go-default vs Connect 404s.
Expand Down Expand Up @@ -658,7 +658,7 @@ def get_side_effect(path, **_kw):
assert "/v1/user" in calls
assert "/server_settings" in calls

out = capsys.readouterr().out
out = capsys.readouterr().err
assert "/server_settings returned HTTP 404" in out
assert "wrong path prefix" in out
assert "https://c.example.com/connect" in out
Expand Down Expand Up @@ -690,7 +690,7 @@ def get_side_effect(path, **_kw):
with patcher:
_create_api_key_via_session(page, "https://c.example.com", "k")

out = capsys.readouterr().out
out = capsys.readouterr().err
assert "/server_settings returned HTTP 200" in out
assert "wrong path prefix" not in out

Expand Down Expand Up @@ -722,7 +722,7 @@ def get_side_effect(path, **_kw):
result = _create_api_key_via_session(page, "https://c.example.com", "k")
assert result is None

out = capsys.readouterr().out
out = capsys.readouterr().err
assert "/server_settings probe failed" in out
assert "probe timed out" in out

Expand All @@ -747,7 +747,7 @@ def raise_connect_error(*_a, **_kw):
with patcher:
assert _create_api_key_via_session(page, "https://c.example.com", "k") is None

assert "simulated TLS rejection" in capsys.readouterr().out
assert "simulated TLS rejection" in capsys.readouterr().err

def test_missing_xsrf_cookie_still_runs(self):
"""With no RSC-XSRF cookie the call still runs; no X-Rsc-Xsrf header sent."""
Expand Down
15 changes: 8 additions & 7 deletions selftests/test_auth_cache.py
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ def test_unwritable_cache_root_skips_caching_without_raising(
finally:
locked.chmod(0o700)

assert "Skipping auth cache" in capsys.readouterr().out
assert "Skipping auth cache" in capsys.readouterr().err
assert not list(work.glob(".vip-auth-cache*"))

def test_skips_cache_when_connect_configured_but_mint_failed(self, tmp_path):
Expand Down Expand Up @@ -172,7 +172,7 @@ def test_unserialisable_meta_leaves_no_cache(self, tmp_path, capsys):

assert not cache.exists()
assert not cache.with_suffix(".meta.json").exists()
assert "Skipping auth cache" in capsys.readouterr().out
assert "Skipping auth cache" in capsys.readouterr().err

@pytest.mark.skipif(sys.platform == "win32", reason="POSIX permission bits")
def test_tightens_an_existing_cache_directory(self, tmp_path):
Expand Down Expand Up @@ -317,7 +317,7 @@ def test_rejects_cache_when_connect_url_differs(self, tmp_path, capsys):
)

assert session is None
assert "Ignoring cached auth session" in capsys.readouterr().out
assert "Ignoring cached auth session" in capsys.readouterr().err

def test_rejects_cache_when_workbench_was_not_recorded(self, tmp_path):
"""A cache minted with only Connect lacks Workbench cookies; a
Expand Down Expand Up @@ -632,7 +632,7 @@ def test_dead_workbench_session_is_a_cache_miss(self, tmp_path, capsys, monkeypa
)

assert session is None
out = capsys.readouterr().out
out = capsys.readouterr().err
assert "Ignoring cached auth session" in out
assert "no longer authenticates Workbench" in out

Expand Down Expand Up @@ -843,7 +843,8 @@ def test_resolving_moves_nothing_and_prints_nothing(self, tmp_path, monkeypatch,
auth_cache_path()

assert len(list(tmp_path.glob(".vip-auth-cache*"))) == 2
assert capsys.readouterr().out == ""
captured = capsys.readouterr()
assert (captured.out, captured.err) == ("", "")

def test_resolving_creates_nothing_without_a_legacy_cache(self, tmp_path, monkeypatch):
from vip.auth import auth_cache_path
Expand Down Expand Up @@ -874,7 +875,7 @@ def test_no_home_directory_skips_the_cache(self, tmp_path, monkeypatch, capsys):

assert prepare_auth_cache() is None

assert "Skipping auth cache" in capsys.readouterr().out
assert "Skipping auth cache" in capsys.readouterr().err
assert set(tmp_path.iterdir()) == before

def test_no_home_directory_leaves_legacy_cache_alone(self, tmp_path, monkeypatch):
Expand Down Expand Up @@ -1499,7 +1500,7 @@ def test_cache_miss_message_quotes_the_detail(self, tmp_path, capsys, monkeypatc
cache, requested_connect_url=None, requested_workbench_url="https://w.example.com"
)

out = capsys.readouterr().out
out = capsys.readouterr().err
assert "Workbench answered 401 Unauthorized" in out
assert "sent back to the sign-in page" not in out

Expand Down
14 changes: 14 additions & 0 deletions selftests/test_auth_headless.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
AuthConfigError,
start_headless_auth,
)
from vip.output import Verbosity, get_verbosity, set_verbosity


class TestStartHeadlessAuthValidation:
Expand All @@ -34,6 +35,19 @@ def test_no_urls_raises_without_cache(self):
with pytest.raises(AuthConfigError, match="at least one product URL"):
start_headless_auth()

def test_verbose_flag_does_not_override_quiet(self):
"""``vip -q verify --headless-auth --verbose`` must stay quiet."""
set_verbosity(Verbosity.QUIET)
with pytest.raises(AuthConfigError):
start_headless_auth(verbose=True)
assert get_verbosity() is Verbosity.QUIET

def test_verbose_flag_raises_normal_to_verbose(self):
set_verbosity(Verbosity.NORMAL)
with pytest.raises(AuthConfigError):
start_headless_auth(verbose=True)
assert get_verbosity() is Verbosity.VERBOSE

def test_invalid_totp_seed_raises_before_playwright(self, monkeypatch):
"""Bad VIP_TEST_TOTP_SECRET fails fast with a clear error."""
monkeypatch.setenv("VIP_TEST_TOTP_SECRET", "not-valid-base32-!!!")
Expand Down
2 changes: 1 addition & 1 deletion selftests/test_auth_interactive.py
Original file line number Diff line number Diff line change
Expand Up @@ -471,7 +471,7 @@ def test_playwright_error_on_goto_is_non_fatal(self, capsys):

result = _authenticate_workbench(page, "https://wb.example.com/pwb")

out = capsys.readouterr().out
out = capsys.readouterr().err
assert "Could not reach Workbench" in out
assert "https://wb.example.com/pwb" in out
assert result is not None
Expand Down
7 changes: 4 additions & 3 deletions selftests/test_auth_scheme.py
Original file line number Diff line number Diff line change
Expand Up @@ -267,7 +267,7 @@ def test_fallback_is_logged_loudly(self, capsys):
with patch("httpx.get", side_effect=httpx.ConnectError("nope")):
resolve_url_scheme(pc)

out = capsys.readouterr().out
out = capsys.readouterr().err
assert "connect.example.com" in out
assert "http://connect.example.com" in out

Expand All @@ -280,7 +280,8 @@ def test_success_is_not_logged(self, capsys):
with patch("httpx.get", return_value=MagicMock(status_code=200)):
resolve_url_scheme(pc)

assert capsys.readouterr().out == ""
captured = capsys.readouterr()
assert (captured.out, captured.err) == ("", "")

def test_mutates_pc_in_place_and_resets_inferred_flag(self):
"""After resolving, pc.url holds the final value and
Expand Down Expand Up @@ -386,7 +387,7 @@ def test_tls_present_but_untrusted_names_the_remedy(self, capsys):
):
resolve_url_scheme(pc)

out = capsys.readouterr().out
out = capsys.readouterr().err
assert "NOT falling back to plaintext" in out
assert "insecure" in out
assert "ca_bundle" in out
Expand Down
8 changes: 4 additions & 4 deletions selftests/test_cli_cleanup.py
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,7 @@ def _fail(*a, **k):

vip.cli.run_cleanup(_make_args(connect_url="https://c.example.com"))

out = capsys.readouterr().out
out = capsys.readouterr().err
assert "Deleted 3 VIP test content item(s)" in out
assert "Cleanup completed successfully" in out

Expand Down Expand Up @@ -211,7 +211,7 @@ def cleanup_vip_content(self):
_make_args(connect_url="https://c.example.com", workbench_url="https://wb.example.com")
)

out = capsys.readouterr().out
out = capsys.readouterr().err
assert "Deleted 1 VIP test content item(s)" in out
assert called["url"] == "https://wb.example.com"

Expand Down Expand Up @@ -687,7 +687,7 @@ def test_clean_token_sweep_skips_browser_auth(self, monkeypatch, capsys):
assert fake.swept_users == ["alice"]
assert fake.init_kwargs["api_key"] == "tok"
assert fake.closed
assert "Quit 2 VIP Workbench session(s) via the API token" in capsys.readouterr().out
assert "Quit 2 VIP Workbench session(s) via the API token" in capsys.readouterr().err

def test_token_without_a_username_does_not_use_the_token_path(self, monkeypatch):
monkeypatch.setattr(
Expand Down Expand Up @@ -727,7 +727,7 @@ def _headless(**kwargs):
)

assert reached == {"headless": True}
assert "falling back to browser sign-in" in capsys.readouterr().out
assert "falling back to browser sign-in" in capsys.readouterr().err

def test_survivors_fall_back_to_browser_auth(self, monkeypatch):
fake = _FakeTokenWorkbenchClient(remaining=[{"id": "a1", "label": "VIP x - main-1"}])
Expand Down
2 changes: 1 addition & 1 deletion selftests/test_cli_url_scheme.py
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,7 @@ def _record_init(self, *a, **k):
vip.cli.run_cleanup(self._args(connect_url="connect.example.com"))

assert constructed == ["http://connect.example.com"]
assert "http://connect.example.com" in capsys.readouterr().out
assert "http://connect.example.com" in capsys.readouterr().err

def test_explicit_scheme_connect_url_never_probes(self, tmp_path, monkeypatch):
monkeypatch.chdir(tmp_path)
Expand Down
Loading
Loading