Added dependency checker and unit test case #2375

mayankmani-sde · 2025-10-17T20:35:36Z

SUMMARY

Added and updated unit tests for validate_dependencies to cover both success and failure scenarios.
Introduced version.py to define the collection version (__version__) for use in dependency checks.
Unit tests use FakeModule and monkey-patched version fetchers for deterministic, environment-independent testing.
Version fetchers (get_python_version, get_zos_version, get_zoau_version) are monkey patched to simulate different Python, z/OS, and ZOAU versions.
Ensures environment-independent, deterministic testing of dependency checks.
Rationale:
Improves test coverage of validate_dependencies across supported and unsupported configurations.
Provides environment-independent, reproducible tests without relying on actual system versions.
Enhances readability and maintainability for future developers by clearly simulating runtime conditions.

ISSUE TYPE

Feature Pull Request

COMPONENT NAME

ADDITIONAL INFORMATION

unit/test_dependency_checker.py::test_validate_dependencies_success ✓                                                                                                            20% ██        
 unit/test_dependency_checker.py::test_validate_dependencies_python_upper ✓                                                                                                       40% ████      
 unit/test_dependency_checker.py::test_validate_dependencies_python_out_of_range ✓                                                                                                60% ██████    
 unit/test_dependency_checker.py::test_validate_dependencies_zos_out_of_range ✓                                                                                                   80% ████████  
 unit/test_dependency_checker.py::test_validate_dependencies_zoau_mismatch ✓                                                                                                     100% ██████████

Results (0.02s):
       5 passed

fernandofloresg · 2025-10-17T20:50:44Z

plugins/module_utils/dependency_checker.py

+# Compatibility Matrix
+# ------------------------------
+COMPATIBILITY_MATRIX = [
+    {"zoau_version": "1.3.5", "python_version": "3.12", "galaxy_core_version": "1.12.0", "zos_range": "2.5-3.1"},


I think it will be easier to use min_zos_version and max_zos_version instead of zos_range and then having to do a string manipulation, same for things that allow ranges like python.

Instead of galaxy_core_version I would use collection_version since we know this is our collection.

Suggested change

{"zoau_version": "1.3.5", "python_version": "3.12", "galaxy_core_version": "1.12.0", "zos_range": "2.5-3.1"},

{"zoau_version": "1.3.5", "python_version": "3.12", "collection_version": "1.12.0", "min_zos_version": "2.5", "max_zos_version": "3.1"},

fernandofloresg · 2025-10-17T20:52:55Z

plugins/module_utils/dependency_checker.py

+# Version Fetchers
+# ------------------------------
+def get_zoau_version(module):
+    output = run_command(module, "zoaversion")


No need to run zoaversion command, as we spoke before better to use the zoau_dependency_checker functionality.

try: from zoautil_py import ZOAU_API_VERSION except Exception: ZOAU_API_VERSION = "1.4.0"

fernandofloresg · 2025-10-17T20:54:56Z

plugins/module_utils/dependency_checker.py

+            return f"{int(match_ver.group(1))}.{int(match_rel.group(1))}"
+    return None
+
+def get_galaxy_core_version():


If we are in the managed node we cannot access the collection version using ansible-galaxy command, this is what we were talking about the other day, is it possible to get through an import by fetching the valye from meta/ibm_zos_core?

fernandofloresg · 2025-10-17T20:57:42Z

plugins/module_utils/dependency_checker.py

+def run_command(module, cmd):
+    rc, out, err = module.run_command(cmd)
+    if rc != 0:
+        module.fail_json(msg=f"Command failed: {cmd}", stdout=out, stderr=err)


This might be problematic, rather than catching the error here I think we should do a try in the main dependency validation, and throw an Exception from there saying something like "The dependencies could not be fetched correctly. " and maybe add some details about the dependencias that were fetched successfully

fernandofloresg · 2025-10-17T21:14:04Z

plugins/module_utils/dependency_checker.py

+    return f"{sys.version_info.major}.{sys.version_info.minor}.0"
+
+def get_zos_version(module):
+    output = run_command(module, "zinfo -t sys -j")


Same, better to use ZOAU's zsystem python API https://www.ibm.com/docs/en/zoau/1.3.x?topic=apis-zsystem we try to avoid using commands when an API is available unless there is a bug in the python API

fernandofloresg · 2025-10-17T21:16:21Z

plugins/module_utils/dependency_checker.py

+    except (ValueError, TypeError):
+        module.fail_json(msg=f"Unable to parse z/OS version: {zos_version}")
+
+    for row in COMPATIBILITY_MATRIX:


Instead of iterating over the compatibility matrix we can use the core collection version as the key to find the correct row and only check the compatibility for the current version

fernandofloresg · 2025-10-17T21:18:55Z

tests/unit/test_dependency_checker_utils.py

@@ -0,0 +1,43 @@
+import pytest
+from ansible_collections.ibm.ibm_zos_core.plugins.module_utils import dependency_checker as dc


For readability, would recommend this to be kept as dependency_checker

fernandofloresg · 2025-10-17T21:26:27Z

tests/unit/test_dependency_checker_utils.py

+
+def test_validate_dependencies_success(monkeypatch):
+    # Monkeypatch fetchers to match the compatibility matrix exactly
+    monkeypatch.setattr(dc, "get_zoau_version", lambda mod: "1.3.5")


I didn't know about this fixture, please add a comment explaining what this does so that next person who sees this doesn't have to spend much time researching why it was implemented this way and not with simple dictionaries as inputs

plugins/module_utils/dependency_checker.py

fernandofloresg

Requested few changes

fernandofloresg · 2025-10-21T19:27:55Z

plugins/module_utils/dependency_checker.py

+COMPATIBILITY_MATRIX = {
+    "2.0.0": {
+        "zoau_version": "1.4.0",
+        "min_python_version": "3.12",


You can pick the python versions from this page:

https://access.redhat.com/support/policy/updates/ansible-automation-platform#phases

Right now we are officially supporting 2.15 trhough 2.18

fernandofloresg · 2025-10-21T21:16:49Z

plugins/module_utils/dependency_checker.py

+        return ZOAU_API_VERSION
+    except ImportError:
+        if module:
+            module.fail_json(msg=" ZOAU Python API not found.")


I would change this error message.

Suggested change

module.fail_json(msg=" ZOAU Python API not found.")

module.fail_json(msg="Unable to import ZOAU. Please check PYTHONPATH, LIBPATH, ZOAU_HOME and PATH environment variables.")

fernandofloresg · 2025-10-21T21:18:23Z

plugins/module_utils/dependency_checker.py

+COMPATIBILITY_MATRIX = {
+    "2.0.0": [
+        {"zoau_version": "1.4.0", "min_python_version": "3.12", "max_python_version": "3.13", "min_zos_version": 2.5, "max_zos_version": 3.1},
+        {"zoau_version": "1.4.1", "min_python_version": "3.12", "max_python_version": "3.13", "min_zos_version": 2.5, "max_zos_version": 3.1},


I don't think there need to add different zoau_version objects here, we can have only min_zoau_version and validate from there

like min_zoau_version: 1.4.0, if current zoau version is 1.4.1 then is ok

fernandofloresg · 2025-10-21T21:25:02Z

plugins/module_utils/dependency_checker.py

+        {"zoau_version": "1.4.2", "min_python_version": "3.12", "max_python_version": "3.13", "min_zos_version": 2.5, "max_zos_version": 3.1},
+    ],
+    "2.1.0": [
+        {"zoau_version": "1.4.1", "min_python_version": "3.12", "max_python_version": "3.13", "min_zos_version": 2.5, "max_zos_version": 3.1},


For the version compatibilities of python you can refer to this

We are currently in AAP 2.3, 2.4 so ansible 2.15-2.18, python version 3.11-3.13 is the current supported version, but this check should be a warning only.

Sorry supported Python version in the managed node is indeed 3.12

fernandofloresg · 2025-10-21T21:29:54Z

plugins/module_utils/dependency_checker.py

+    # Ensure all versions are available
+    if not all([zoau_version, zos_version_str, collection_version]):
+        module.fail_json(
+            msg=" Missing one or more required versions (ZOAU, Python, z/OS, Collection Version)."


This mentions python but is not checked in line 100. Also, lets change the message:

Suggested change

msg=" Missing one or more required versions (ZOAU, Python, z/OS, Collection Version)."

msg="Unable to fetch one or more required dependencies. Depedencies checked are ZOAU, Python, z/OS."

fernandofloresg · 2025-10-21T21:33:00Z

plugins/module_utils/dependency_checker.py

+    """Fetch z/OS version using ZOAU Python API and return a string like '2.5'."""
+    if zsystem is None:
+        if module:
+            module.fail_json(msg="ZOAU Python API not found.")


Suggested change

module.fail_json(msg="ZOAU Python API not found.")

module.fail_json(msg="Unable to import ZOAU. Please check PYTHONPATH, LIBPATH, ZOAU_HOME and PATH environment variables.")

fernandofloresg · 2025-10-22T15:35:15Z

plugins/module_utils/dependency_checker.py

+        {"zoau_version": "1.4.2", "min_python_version": "3.12", "max_python_version": "3.13", "min_zos_version": 2.5, "max_zos_version": 3.1},
+    ],
+    "2.1.0": [
+        {"zoau_version": "1.4.1", "min_python_version": "3.12", "max_python_version": "3.13", "min_zos_version": 2.5, "max_zos_version": 3.1},


Sorry supported Python version in the managed node is indeed 3.12

fernandofloresg

Partial Review, need to go back an check the messages

plugins/module_utils/dependency_checker.py

Added dependency checker and unit test case

74031fd

fernandofloresg requested changes Oct 17, 2025

View reviewed changes

mayankmani-sde added 9 commits October 21, 2025 19:08

pushed requested changes

9be3bab

added header

5ab1feb

added python range 3.12-3.13

799542d

updated mock test

0f2235d

updated version

e860507

added header in test

80f5d28

removed alias dc from test

701d066

added header in test

f2718fd

added comment in test

c550b0c

mayankmani-sde marked this pull request as ready for review October 21, 2025 19:13

mayankmani-sde added 2 commits October 22, 2025 01:06

fixed sanity

7aa1be3

FIXED SANITY

a19b2b7

mayankmani-sde requested review from fernandofloresg and removed request for fernandofloresg October 21, 2025 19:43

fixed sanity

217012c

mayankmani-sde requested a review from fernandofloresg October 21, 2025 20:05

fernandofloresg requested changes Oct 21, 2025

View reviewed changes

fernandofloresg reviewed Oct 22, 2025

View reviewed changes

mayankmani-sde added 6 commits October 22, 2025 21:55

changed error message

74d7afd

checked for Ensure all versions are available and fixed error message

079ab14

removed code for range check for max versions of python and zos

7b37786

added warning message

90a2c07

enhanced error message

5be0f12

fixed sanity

14f0424

mayankmani-sde requested a review from fernandofloresg October 22, 2025 20:06

added comment in test

6edc75d

mayankmani-sde linked an issue Oct 24, 2025 that may be closed by this pull request

[Enhancement][2.0] Implement dependency checker for all modules in the collection #2133

Open

6 tasks

fernandofloresg requested changes Oct 24, 2025

View reviewed changes

plugins/module_utils/dependency_checker.py Outdated Show resolved Hide resolved

plugins/module_utils/dependency_checker.py Outdated Show resolved Hide resolved

plugins/module_utils/dependency_checker.py Outdated Show resolved Hide resolved

mayankmani-sde added 5 commits October 25, 2025 01:31

fixed

519c0ef

typo error

bd1a5ee

fixed

d2b05e4

fixed

d8baed7

typo error

1348507

mayankmani-sde requested a review from fernandofloresg October 24, 2025 20:29

mayankmani-sde added 15 commits November 5, 2025 13:19

enhamced code

ddb9b7f

enhamced unit test case

130963a

fixed

ada03b2

fixed

a0d535e

fixed

8018bef

added integration of dependency_checker in zos_apf module

59a13d3

added integration of dependency_checker in zos_archive

27d8cf8

added integration of dependency_checker module in zos_backup_restore

c1617c9

added integration for dependency_checker in zos_blockinfile

f0a7062

added dependency_checker in all modules except zos_volume_init.py

8ccdb1f

added dependency-checker in zos_volume_init.py

47db734

Merge branch 'dev' into Enhancement/2133/Dependency_checker

2626457

FIXED

d4d9fe8

enhanced

665ea6b

updated dependency matrix from 1.3.6.0 to 1.4.0

874028b

	{"zoau_version": "1.3.5", "python_version": "3.12", "galaxy_core_version": "1.12.0", "zos_range": "2.5-3.1"},
	{"zoau_version": "1.3.5", "python_version": "3.12", "collection_version": "1.12.0", "min_zos_version": "2.5", "max_zos_version": "3.1"},

		@@ -0,0 +1,43 @@
		import pytest
		from ansible_collections.ibm.ibm_zos_core.plugins.module_utils import dependency_checker as dc

	module.fail_json(msg=" ZOAU Python API not found.")
	module.fail_json(msg="Unable to import ZOAU. Please check PYTHONPATH, LIBPATH, ZOAU_HOME and PATH environment variables.")

	msg=" Missing one or more required versions (ZOAU, Python, z/OS, Collection Version)."
	msg="Unable to fetch one or more required dependencies. Depedencies checked are ZOAU, Python, z/OS."

	module.fail_json(msg="ZOAU Python API not found.")
	module.fail_json(msg="Unable to import ZOAU. Please check PYTHONPATH, LIBPATH, ZOAU_HOME and PATH environment variables.")

Added dependency checker and unit test case #2375

Are you sure you want to change the base?

Added dependency checker and unit test case #2375

Uh oh!

Conversation

mayankmani-sde commented Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

SUMMARY

ISSUE TYPE

COMPONENT NAME

ADDITIONAL INFORMATION

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

fernandofloresg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fernandofloresg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mayankmani-sde commented Oct 17, 2025 •

edited

Loading