Address review: fix compatibility bug, improve docs, add tests

- Pass compatibility= from create_task() to edit_task() (was silently
  dropped since it is a named param, not in **kwargs)
- Fix `if compatibility:` to `if compatibility is not None:` so that
  value 0 (AT/Windows 2000) is not skipped
- Expand docstrings for compatibility in create_task and edit_task to
  list what each integer value means
- Add unit tests in test_win_task_compatibility.py that mock COM and
  verify compatibility is set correctly for all four values, and that
  create_task forwards the parameter to edit_task

Author: dwoz

salt/modules/win_task.py

@@ -530,7 +530,13 @@ def list_actions(name, location="\\"):
 
 
 def create_task(
-    name, location="\\", user_name="System", password=None, force=False, compatibility=2, **kwargs
+    name,
+    location="\\",
+    user_name="System",
+    password=None,
+    force=False,
+    compatibility=2,
+    **kwargs,
 ):
     r"""
     Create a new task in the designated location. This function has many keyword
@@ -571,9 +577,15 @@ def create_task(
             Default is ``False``.
 
         compatibility (:obj:`int`, optional):
-            The task compatibility level
+            The task compatibility level. Determines which versions of Windows
+            the task is compatible with. Valid values are:
 
-            Default is 2
+            - 0: Windows Server 2003, Windows XP, or Windows 2000
+            - 1: Windows Vista, Windows Server 2008 (V1 task)
+            - 2: Windows 7, Windows Server 2008 R2 (V2 task, default)
+            - 3: Windows 10
+
+            Default is ``2``.
 
     Returns:
         bool: ``True`` if successful, otherwise ``False``.
@@ -602,6 +614,7 @@ def create_task(
             task_definition=task_definition,
             user_name=user_name,
             password=password,
+            compatibility=compatibility,
             **kwargs,
         )
 
@@ -1077,12 +1090,13 @@ def edit_task(
             Default is ``None``.
 
         compatibility (:obj:`int`, optional):
-            Sets the task compatibility level. Valid values are:
-            
-            - 0
-            - 1
-            - 2
-            - 3
+            Sets the task compatibility level. Determines which versions of
+            Windows the task is compatible with. Valid values are:
+
+            - 0: Windows Server 2003, Windows XP, or Windows 2000
+            - 1: Windows Vista, Windows Server 2008 (V1 task)
+            - 2: Windows 7, Windows Server 2008 R2 (V2 task)
+            - 3: Windows 10
 
             Default is ``None``.
 
@@ -1164,7 +1178,7 @@ def edit_task(
         # Settings: General Tab
         if hidden is not None:
             task_definition.Settings.Hidden = hidden
-        if compatibility:
+        if compatibility is not None:
             task_definition.Settings.Compatibility = compatibility
 
         # Settings: Conditions Tab (Idle)

tests/pytests/unit/modules/test_win_task_compatibility.py

@@ -0,0 +1,109 @@
+"""
+Unit tests for the compatibility parameter in win_task.create_task and
+win_task.edit_task. These tests use mocks and run on any platform.
+"""
+
+import sys
+import types
+
+import pytest
+
+from tests.support.mock import MagicMock, patch
+
+# Inject a stub win32com into sys.modules if not already present so that
+# salt.modules.win_task can be imported on non-Windows hosts.
+if "win32com" not in sys.modules:
+    _win32com = types.ModuleType("win32com")
+    _win32com_client = types.ModuleType("win32com.client")
+    _win32com_client.Dispatch = MagicMock()
+    _win32com.client = _win32com_client
+    sys.modules["win32com"] = _win32com
+    sys.modules["win32com.client"] = _win32com_client
+if "pythoncom" not in sys.modules:
+    sys.modules["pythoncom"] = types.ModuleType("pythoncom")
+if "pywintypes" not in sys.modules:
+    sys.modules["pywintypes"] = types.ModuleType("pywintypes")
+
+import salt.modules.win_task as win_task  # noqa: E402
+
+
+@pytest.mark.parametrize(
+    "compatibility",
+    [
+        0,  # Windows 2000/XP/2003
+        1,  # Windows Vista/2008 (V1 task)
+        2,  # Windows 7/2008 R2 (V2 task)
+        3,  # Windows 10
+    ],
+)
+def test_edit_task_compatibility(compatibility):
+    """
+    edit_task sets Settings.Compatibility to the given value when a
+    task_definition is passed directly (no COM lookup needed).
+    """
+    mock_task_def = MagicMock()
+    mock_task_def.Principal.UserID = "SYSTEM"
+    mock_task_def.Principal.LogonType = 5  # TASK_LOGON_SERVICE_ACCOUNT
+
+    with patch("salt.utils.winapi.Com", MagicMock()):
+        win_task.edit_task(
+            task_definition=mock_task_def,
+            compatibility=compatibility,
+        )
+
+    assert mock_task_def.Settings.Compatibility == compatibility
+
+
+def test_edit_task_compatibility_none_leaves_unset():
+    """
+    edit_task does not touch Settings.Compatibility when compatibility=None.
+    """
+    mock_task_def = MagicMock()
+    mock_task_def.Principal.UserID = "SYSTEM"
+    mock_task_def.Principal.LogonType = 5
+
+    # Snapshot the auto-generated MagicMock child before the call
+    sentinel = mock_task_def.Settings.Compatibility
+
+    with patch("salt.utils.winapi.Com", MagicMock()):
+        win_task.edit_task(
+            task_definition=mock_task_def,
+            compatibility=None,
+        )
+
+    # If the branch was skipped, the attribute is still the same mock object
+    assert mock_task_def.Settings.Compatibility is sentinel
+
+
+def test_create_task_passes_compatibility_to_edit_task():
+    """
+    create_task forwards its compatibility= argument to edit_task so that
+    Settings.Compatibility is set on the new task definition.
+    """
+    mock_task_def = MagicMock()
+    mock_task_def.Principal.UserID = "SYSTEM"
+    mock_task_def.Principal.LogonType = 5
+
+    mock_task_service = MagicMock()
+    mock_task_service.NewTask.return_value = mock_task_def
+
+    with (
+        patch("salt.utils.winapi.Com", MagicMock()),
+        patch.object(
+            win_task.win32com.client, "Dispatch", return_value=mock_task_service
+        ),
+        patch.object(win_task, "list_tasks", return_value=[]),
+        patch.object(win_task, "add_action", return_value=True),
+        patch.object(win_task, "add_trigger", return_value=True),
+        patch.object(win_task, "_save_task_definition", return_value=True),
+    ):
+        win_task.create_task(
+            "TestTask",
+            user_name="System",
+            force=True,
+            compatibility=1,
+            action_type="Execute",
+            cmd="cmd.exe",
+        )
+
+    assert mock_task_def.Settings.Compatibility == 1