test(common): Add tests for tmux version deprecation warning

Author: tony

tests/test_common.py

@@ -508,3 +508,68 @@ def mock_get_version() -> LooseVersion:
     elif check_type == "type_check":
         assert mock_version is not None  # For type checker
         assert isinstance(has_version(mock_version), bool)
+
+
+class TestVersionDeprecationWarning:
+    """Tests for tmux version deprecation warnings."""
+
+    def test_deprecated_version_warns_once(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Warn once when tmux version is below TMUX_SOFT_MIN_VERSION."""
+        import warnings
+
+        import libtmux.common
+
+        # Reset the warning flag
+        monkeypatch.setattr(libtmux.common, "_version_deprecation_checked", False)
+
+        # Clear any env var that might suppress
+        monkeypatch.delenv("LIBTMUX_SUPPRESS_VERSION_WARNING", raising=False)
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            libtmux.common._check_deprecated_version(LooseVersion("3.1"))
+            libtmux.common._check_deprecated_version(LooseVersion("3.1"))
+
+        assert len(w) == 1
+        assert issubclass(w[0].category, DeprecationWarning)
+        assert "3.1" in str(w[0].message)
+        assert "3.2a" in str(w[0].message)
+
+    def test_current_version_no_warning(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """No warning when tmux version meets minimum."""
+        import warnings
+
+        import libtmux.common
+
+        monkeypatch.setattr(libtmux.common, "_version_deprecation_checked", False)
+        monkeypatch.delenv("LIBTMUX_SUPPRESS_VERSION_WARNING", raising=False)
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            libtmux.common._check_deprecated_version(LooseVersion("3.2a"))
+
+        assert len(w) == 0
+
+    def test_env_var_suppresses_warning(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """LIBTMUX_SUPPRESS_VERSION_WARNING suppresses deprecation warning."""
+        import warnings
+
+        import libtmux.common
+
+        monkeypatch.setattr(libtmux.common, "_version_deprecation_checked", False)
+        monkeypatch.setenv("LIBTMUX_SUPPRESS_VERSION_WARNING", "1")
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            libtmux.common._check_deprecated_version(LooseVersion("3.0"))
+
+        assert len(w) == 0