nac-test-pyats-common 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

nac_test_pyats_common/common/base_device_resolver.py

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2025 Daniel Schmidt
+
 """Base device resolver for SSH/D2D testing.
 
 Provides the Template Method pattern for device inventory resolution.
@@ -5,14 +8,12 @@ Architecture-specific resolvers extend this class and implement the
 abstract methods for schema navigation and credential retrieval.
 """
 
+import ipaddress
 import logging
 import os
 from abc import ABC, abstractmethod
 from typing import Any
 
-import yaml
-from nac_test.utils.file_discovery import find_data_file
-
 logger = logging.getLogger(__name__)
 
 
@@ -20,28 +21,27 @@ class BaseDeviceResolver(ABC):
     """Abstract base class for architecture-specific device resolvers.
 
     This class implements the Template Method pattern for device inventory
-    resolution. It handles common logic (inventory loading, credential
-    injection, device dict construction) while delegating schema-specific
-    work to abstract methods.
+    resolution. It handles common logic (credential injection, device dict
+    construction) while delegating schema-specific work to abstract methods.
 
     Subclasses MUST implement:
         - get_architecture_name(): Return architecture identifier (e.g., "sdwan")
         - get_schema_root_key(): Return the root key in data model (e.g., "sdwan")
         - navigate_to_devices(): Navigate schema to get iterable of device data
-        - extract_device_id(): Extract unique device identifier from device data
         - extract_hostname(): Extract hostname from device data
         - extract_host_ip(): Extract management IP from device data
         - extract_os_type(): Extract OS type from device data
         - get_credential_env_vars(): Return (username_env_var, password_env_var)
 
     Subclasses MAY override:
-        - get_inventory_filename(): Return inventory filename (default: "test_inventory.yaml")
+        - extract_device_id(): Extract device identifier (default: uses hostname)
         - build_device_dict(): Customize device dict construction
-        - _load_inventory(): Customize inventory loading
+        - validate_device_data(): Pre-extraction validation hook
 
     Attributes:
         data_model: The merged NAC data model dictionary.
-        test_inventory: The test inventory dictionary (devices to test).
+        skipped_devices: List of dicts with device_id and reason for devices
+            that failed resolution. Populated after get_resolved_inventory().
 
     Example:
         >>> class SDWANDeviceResolver(BaseDeviceResolver):
@@ -57,33 +57,24 @@ class BaseDeviceResolver(ABC):
         >>> devices = resolver.get_resolved_inventory()
     """
 
-    def __init__(
-        self,
-        data_model: dict[str, Any],
-        test_inventory: dict[str, Any] | None = None,
-    ) -> None:
+    def __init__(self, data_model: dict[str, Any]) -> None:
         """Initialize the device resolver.
 
         Args:
             data_model: The merged NAC data model containing all architecture
                 data with resolved variables.
-            test_inventory: Optional test inventory specifying which devices
-                to test. If not provided, will attempt to load from file.
         """
         self.data_model = data_model
-        self.test_inventory = test_inventory or self._load_inventory()
-        logger.debug(
-            f"Initialized {self.get_architecture_name()} resolver with "
-            f"{len(self.test_inventory.get('devices', []))} devices in inventory"
-        )
+        self.skipped_devices: list[dict[str, str]] = []
+        logger.debug(f"Initialized {self.get_architecture_name()} resolver")
 
     def get_resolved_inventory(self) -> list[dict[str, Any]]:
         """Get resolved device inventory ready for SSH connection.
 
         This is the main entry point. It:
         1. Navigates the data model to find device data
-        2. Matches devices against test inventory (if provided)
-        3. Extracts hostname, IP, OS from each device
+        2. Extracts hostname and management IP from each device
+        3. Sets OS type (architecture-specific, e.g., hardcoded to 'iosxe' for SD-WAN)
         4. Injects SSH credentials from environment variables
         5. Returns list of device dicts ready for nac-test
 
@@ -102,10 +93,15 @@ class BaseDeviceResolver(ABC):
         logger.info(f"Resolving device inventory for {self.get_architecture_name()}")
 
         resolved_devices: list[dict[str, Any]] = []
-        devices_to_test = self._get_devices_to_test()
+        self.skipped_devices = []  # Reset for each resolution
+        all_devices = list(self.navigate_to_devices())
+        logger.debug(f"Found {len(all_devices)} devices in data model")
 
-        for device_data in devices_to_test:
+        for device_data in all_devices:
             try:
+                # Validate device data before extraction (optional hook)
+                self.validate_device_data(device_data)
+
                 device_dict = self.build_device_dict(device_data)
 
                 # Validate extracted fields
@@ -125,18 +121,53 @@ class BaseDeviceResolver(ABC):
                 )
             except (KeyError, ValueError) as e:
                 device_id = self._safe_extract_device_id(device_data)
-                logger.warning(f"Skipping device {device_id}: {e}")
+                logger.debug(f"Skipping device {device_id}: {e}")
+                self.skipped_devices.append(
+                    {
+                        "device_id": device_id,
+                        "reason": str(e),
+                    }
+                )
                 continue
 
         # Inject credentials (fail fast if missing)
         self._inject_credentials(resolved_devices)
 
+        skipped_msg = (
+            f", skipped {len(self.skipped_devices)}" if self.skipped_devices else ""
+        )
         logger.info(
             f"Resolved {len(resolved_devices)} devices for "
-            f"{self.get_architecture_name()} D2D testing"
+            f"{self.get_architecture_name()} D2D testing{skipped_msg}"
         )
         return resolved_devices
 
+    def validate_device_data(self, _device_data: dict[str, Any]) -> None:  # noqa: B027
+        """Validate device data before extraction (optional hook).
+
+        Override this method to perform architecture-specific validation
+        before device field extraction. This is useful for filtering devices
+        based on state, type, or other criteria.
+
+        The default implementation does nothing - all devices pass validation.
+        Subclasses can override this to implement custom validation logic.
+
+        Args:
+            _device_data: Raw device data from the data model (unused in base class).
+
+        Raises:
+            ValueError: If the device should be skipped. The error message
+                will be logged and included in skipped_devices tracking.
+
+        Example (Catalyst Center - skip devices in INIT/PNP states):
+            >>> def validate_device_data(self, device_data):
+            ...     state = device_data.get("state", "").upper()
+            ...     if state in ("INIT", "PNP"):
+            ...         raise ValueError(f"Device has unsupported state '{state}'")
+        """
+        # Default implementation does nothing - subclasses can override
+        pass
+
     def build_device_dict(self, device_data: dict[str, Any]) -> dict[str, Any]:
         """Build a device dictionary from raw device data.
 
@@ -147,8 +178,7 @@ class BaseDeviceResolver(ABC):
             device_data: Raw device data from the data model.
 
         Returns:
-            Device dictionary with hostname, host, os, device_id fields,
-            plus any test-relevant fields like connection_options.
+            Device dictionary with hostname, host, os, device_id fields.
             Credentials are injected separately.
 
         Raises:
@@ -164,146 +194,31 @@ class BaseDeviceResolver(ABC):
             raise ValueError(f"Invalid hostname: {hostname!r}")
         if not isinstance(host, str) or not host:
             raise ValueError(f"Invalid host IP: {host!r}")
+
+        # Validate IP address format (after CIDR stripping done by subclass)
+        try:
+            ipaddress.ip_address(host)
+        except ValueError:
+            raise ValueError(
+                f"Invalid IP address format: '{host}'. "
+                "Ensure the field contains a valid IPv4 or IPv6 address."
+            ) from None
         if not isinstance(os_type, str) or not os_type:
             raise ValueError(f"Invalid OS type: {os_type!r}")
         if not isinstance(device_id, str) or not device_id:
             raise ValueError(f"Invalid device ID: {device_id!r}")
 
-        # Start with required fields
-        result = {
+        return {
             "hostname": hostname,
             "host": host,
             "os": os_type,
             "device_id": device_id,
         }
 
-        # Preserve connection_options from test_inventory if present
-        # This allows specifying custom SSH ports, protocols, etc.
-        if "connection_options" in device_data:
-            result["connection_options"] = device_data["connection_options"]
-
-        return result
-
     # -------------------------------------------------------------------------
     # Private helper methods
     # -------------------------------------------------------------------------
 
-    def _load_inventory(self) -> dict[str, Any]:
-        """Load test inventory from file.
-
-        Searches for the inventory file using the generic file discovery
-        utility. Subclasses can override this to customize loading behavior.
-
-        Returns:
-            Test inventory dictionary, or empty dict if not found.
-        """
-        filename = self.get_inventory_filename()
-        inventory_path = find_data_file(filename)
-
-        if inventory_path is None:
-            logger.warning(
-                f"Test inventory file '{filename}' not found for "
-                f"{self.get_architecture_name()}. Using empty inventory."
-            )
-            return {}
-
-        logger.info(f"Loading test inventory from {inventory_path}")
-        try:
-            with open(inventory_path) as f:
-                raw_data = yaml.safe_load(f) or {}
-
-            # Support both nested and flat formats:
-            # Nested: {arch: {test_inventory: {...}}}
-            # Flat: {test_inventory: {...}}
-            arch_key = self.get_schema_root_key()
-            if arch_key in raw_data and "test_inventory" in raw_data[arch_key]:
-                return raw_data[arch_key]["test_inventory"]  # type: ignore[no-any-return]
-            elif "test_inventory" in raw_data:
-                return raw_data["test_inventory"]  # type: ignore[no-any-return]
-            else:
-                return raw_data
-
-        except yaml.YAMLError as e:
-            logger.error(f"Failed to parse test inventory YAML: {e}")
-            return {}
-        except OSError as e:
-            logger.error(f"Failed to read test inventory file: {e}")
-            return {}
-
-    def _get_devices_to_test(self) -> list[dict[str, Any]]:
-        """Get the list of device data dicts to process.
-
-        If test_inventory specifies devices, filter to only those.
-        Otherwise, return all devices from the data model.
-
-        Returns:
-            List of device data dictionaries from the data model.
-        """
-        all_devices = list(self.navigate_to_devices())
-        logger.debug(f"Found {len(all_devices)} total devices in data model")
-
-        # If no test inventory, test all devices
-        inventory_devices = self.test_inventory.get("devices", [])
-        if not inventory_devices:
-            logger.debug("No test inventory devices specified, testing all devices")
-            return all_devices
-
-        # Build index for efficient lookup
-        device_index = self._build_device_index(all_devices)
-
-        # Filter to devices in test inventory
-        devices_to_test: list[dict[str, Any]] = []
-        for inventory_entry in inventory_devices:
-            device_id = self._get_device_id_from_inventory(inventory_entry)
-            if device_id in device_index:
-                # Merge inventory entry data with device data
-                merged = {**device_index[device_id], **inventory_entry}
-                devices_to_test.append(merged)
-                logger.debug(f"Added device {device_id} from test inventory")
-            else:
-                logger.warning(
-                    f"Device '{device_id}' from test_inventory not found in "
-                    f"{self.get_architecture_name()} data model"
-                )
-
-        logger.debug(f"Filtered to {len(devices_to_test)} devices from test inventory")
-        return devices_to_test
-
-    def _build_device_index(self, devices: list[dict[str, Any]]) -> dict[str, dict[str, Any]]:
-        """Build a lookup index of devices by their ID.
-
-        Args:
-            devices: List of device data dictionaries.
-
-        Returns:
-            Dictionary mapping device ID to device data.
-        """
-        device_index: dict[str, dict[str, Any]] = {}
-        for device_data in devices:
-            device_id = self._safe_extract_device_id(device_data)
-            if device_id:
-                device_index[device_id] = device_data
-        return device_index
-
-    def _get_device_id_from_inventory(self, inventory_entry: dict[str, Any]) -> str:
-        """Extract device ID from a test inventory entry.
-
-        Override this if your inventory uses a different field name.
-
-        Args:
-            inventory_entry: Entry from test_inventory.devices[]
-
-        Returns:
-            Device identifier string.
-        """
-        # Common patterns across architectures
-        for key in ["chassis_id", "device_id", "node_id", "hostname", "name"]:
-            if key in inventory_entry:
-                return str(inventory_entry[key])
-
-        logger.warning(f"Could not extract device ID from inventory entry: {inventory_entry}")
-        return ""
-
     def _safe_extract_device_id(self, device_data: dict[str, Any]) -> str:
         """Safely extract device ID, returning empty string on failure."""
         try:
@@ -333,7 +248,8 @@ class BaseDeviceResolver(ABC):
 
         if missing_vars:
             raise ValueError(
-                f"Missing required credential environment variables: {', '.join(missing_vars)}. "
+                f"Missing required credential environment variables: "
+                f"{', '.join(missing_vars)}. "
                 f"These are required for {self.get_architecture_name()} D2D testing."
             )
 
@@ -361,7 +277,7 @@ class BaseDeviceResolver(ABC):
     def get_schema_root_key(self) -> str:
         """Return the root key in the data model for this architecture.
 
-        Used when loading test inventory and navigating the schema.
+        Used when navigating the schema.
 
         Returns:
             Root key (e.g., "sdwan", "apic", "cc").
@@ -387,11 +303,14 @@ class BaseDeviceResolver(ABC):
         """
         ...
 
-    @abstractmethod
     def extract_device_id(self, device_data: dict[str, Any]) -> str:
         """Extract unique device identifier from device data.
 
-        This ID is used to match test_inventory entries with data model devices.
+        Default implementation delegates to extract_hostname(), which is
+        appropriate when device_id and hostname are the same field.
+
+        Override this method when your architecture has a distinct device
+        identifier (e.g., SD-WAN uses chassis_id, not hostname).
 
         Args:
             device_data: Device data dict from navigate_to_devices().
@@ -399,11 +318,11 @@ class BaseDeviceResolver(ABC):
         Returns:
             Unique device identifier string.
 
-        Example (SD-WAN):
+        Example (SD-WAN override):
             >>> def extract_device_id(self, device_data):
             ...     return device_data["chassis_id"]
         """
-        ...
+        return self.extract_hostname(device_data)
 
     @abstractmethod
     def extract_hostname(self, device_data: dict[str, Any]) -> str:
@@ -426,6 +345,8 @@ class BaseDeviceResolver(ABC):
         """Extract management IP address from device data.
 
         Should handle any IP formatting (e.g., strip CIDR notation).
+        The returned value will be validated by the base class to ensure
+        it is a valid IPv4 or IPv6 address.
 
         Args:
             device_data: Device data dict from navigate_to_devices().
@@ -435,7 +356,7 @@ class BaseDeviceResolver(ABC):
 
         Example (SD-WAN):
             >>> def extract_host_ip(self, device_data):
-            ...     ip_var = device_data.get("management_ip_variable", "mgmt_ip")
+            ...     ip_var = device_data.get("management_ip_variable")
             ...     ip = device_data["device_variables"].get(ip_var, "")
             ...     return ip.split("/")[0] if "/" in ip else ip
         """
@@ -476,17 +397,3 @@ class BaseDeviceResolver(ABC):
             ...     return ("NXOS_SSH_USERNAME", "NXOS_SSH_PASSWORD")
         """
         ...
-
-    # -------------------------------------------------------------------------
-    # Optional overrides
-    # -------------------------------------------------------------------------
-
-    def get_inventory_filename(self) -> str:
-        """Return the test inventory filename.
-
-        Override to use a different filename.
-
-        Returns:
-            Filename (default: "test_inventory.yaml").
-        """
-        return "test_inventory.yaml"

nac_test_pyats_common/iosxe/__init__.py

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2025 Daniel Schmidt
+
 """IOS-XE adapter module for NAC PyATS testing.
 
 This module provides a generic IOS-XE test base class and resolver registry

nac_test_pyats_common/iosxe/iosxe_resolver.py

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2025 Daniel Schmidt
+
 """IOSXE device resolver placeholder for direct IOS-XE device access.
 
 This is a placeholder for the IOSXE resolver that will be implemented

nac_test_pyats_common/iosxe/registry.py

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2025 Daniel Schmidt
+
 """Registry for IOS-XE device resolvers.
 
 This module implements a plugin architecture for registering and retrieving
@@ -79,20 +82,24 @@ def register_iosxe_resolver(controller_type: str) -> Callable[[type[T]], type[T]
         """
         # Validate the class extends BaseDeviceResolver
         if not issubclass(cls, BaseDeviceResolver):
-            raise TypeError(f"Resolver class {cls.__name__} must extend BaseDeviceResolver")
+            raise TypeError(
+                f"Resolver class {cls.__name__} must extend BaseDeviceResolver"
+            )
 
         # Check for duplicate registration
         if controller_type in _IOSXE_RESOLVER_REGISTRY:
             existing_class = _IOSXE_RESOLVER_REGISTRY[controller_type]
             raise ValueError(
-                f"A resolver is already registered for controller type '{controller_type}': "
+                f"A resolver is already registered for controller type "
+                f"'{controller_type}': "
                 f"{existing_class.__module__}.{existing_class.__name__}"
             )
 
         # Register the resolver
         _IOSXE_RESOLVER_REGISTRY[controller_type] = cls
         logger.debug(
-            f"Registered IOS-XE resolver {cls.__name__} for controller type '{controller_type}'"
+            f"Registered IOS-XE resolver {cls.__name__} for controller type "
+            f"'{controller_type}'"
         )
 
         return cls
@@ -100,7 +107,9 @@ def register_iosxe_resolver(controller_type: str) -> Callable[[type[T]], type[T]
     return decorator
 
 
-def get_resolver_for_controller(controller_type: str) -> type[BaseDeviceResolver] | None:
+def get_resolver_for_controller(
+    controller_type: str,
+) -> type[BaseDeviceResolver] | None:
     """Get the device resolver class for a specific controller type.
 
     Retrieves the registered resolver class for the specified controller type.
@@ -124,7 +133,8 @@ def get_resolver_for_controller(controller_type: str) -> type[BaseDeviceResolver
 
     if resolver_class:
         logger.debug(
-            f"Found resolver {resolver_class.__name__} for controller type '{controller_type}'"
+            f"Found resolver {resolver_class.__name__} for controller type "
+            f"'{controller_type}'"
         )
     else:
         logger.debug(

nac_test_pyats_common/iosxe/test_base.py

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2025 Daniel Schmidt
+
 """IOS-XE test base class for SSH/D2D testing."""
 
 import os
@@ -18,8 +21,15 @@ class IOSXETestBase(SSHTestBase):  # type: ignore[misc]
     - IOS-XE (direct device access via IOSXE_URL)
     """
 
+    # Class-level storage for the last resolver instance
+    # This allows nac-test to access skipped_devices after calling
+    # get_ssh_device_inventory()
+    _last_resolver: Any = None
+
     @classmethod
-    def get_ssh_device_inventory(cls, data_model: dict[str, Any]) -> list[dict[str, Any]]:
+    def get_ssh_device_inventory(
+        cls, data_model: dict[str, Any]
+    ) -> list[dict[str, Any]]:
         """Get the SSH device inventory for IOS-XE devices.
 
         Main entry point that detects the architecture and returns
@@ -58,6 +68,7 @@ class IOSXETestBase(SSHTestBase):  # type: ignore[misc]
                 f"No device resolver registered for controller type '{controller_type}'"
             )
         resolver = resolver_class(data_model)
+        cls._last_resolver = resolver  # Store for skipped_devices access
 
         # Inline validation: Check data model has expected root key
         expected_keys = {

nac_test_pyats_common/sdwan/__init__.py

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2025 Daniel Schmidt
+
 """SD-WAN (SDWAN Manager) adapter module for NAC PyATS testing.
 
 This module provides SD-WAN-specific authentication, test base classes, and device
@@ -5,7 +8,8 @@ resolver implementations for use with the nac-test framework. It includes suppor
 for both SDWAN Manager API testing and SSH-based device-to-device (D2D) testing.
 
 Classes:
-    SDWANManagerAuth: SDWAN Manager authentication with JSESSIONID and XSRF token management.
+    SDWANManagerAuth: SDWAN Manager authentication with JSESSIONID and XSRF token
+        management.
     SDWANManagerTestBase: Base class for SDWAN Manager API tests with tracking.
     SDWANTestBase: Base class for SD-WAN SSH/D2D tests with device inventory.
     SDWANDeviceResolver: Resolves device information from the SD-WAN data model.

nac_test_pyats_common/sdwan/api_test_base.py

@@ -1,9 +1,13 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2025 Daniel Schmidt
+
 """SDWAN Manager-specific base test class for SD-WAN API testing.
 
-This module provides the SDWANManagerTestBase class, which extends the generic NACTestBase
-to add SDWAN Manager-specific functionality for testing SD-WAN controllers. It handles
-session management (JSESSIONID and XSRF token), client configuration, and provides
-a standardized interface for running asynchronous verification tests against SDWAN Manager.
+This module provides the SDWANManagerTestBase class, which extends the generic
+NACTestBase to add SDWAN Manager-specific functionality for testing SD-WAN
+controllers. It handles session management (JSESSIONID and XSRF token), client
+configuration, and provides a standardized interface for running asynchronous
+verification tests against SDWAN Manager.
 
 The class integrates with PyATS/Genie test frameworks and provides automatic
 API call tracking for enhanced HTML reporting.
@@ -13,7 +17,9 @@ import asyncio
 from typing import Any
 
 import httpx
-from nac_test.pyats_core.common.base_test import NACTestBase  # type: ignore[import-untyped]
+from nac_test.pyats_core.common.base_test import (
+    NACTestBase,  # type: ignore[import-untyped]
+)
 from pyats import aetest  # type: ignore[import-untyped]
 
 from .auth import SDWANManagerAuth
@@ -43,7 +49,8 @@ class SDWANManagerTestBase(NACTestBase):  # type: ignore[misc]
 
     Methods:
         setup(): Initialize SDWAN Manager authentication and client.
-        get_sdwan_manager_client(): Create and configure an SDWAN Manager-specific HTTP client.
+        get_sdwan_manager_client(): Create and configure an SDWAN Manager-specific
+            HTTP client.
         run_async_verification_test(): Execute async verification tests with PyATS.
 
     Example:
@@ -68,7 +75,8 @@ class SDWANManagerTestBase(NACTestBase):  # type: ignore[misc]
 
         Initializes the SDWAN Manager test environment by:
         1. Calling the parent class setup method
-        2. Obtaining SDWAN Manager session data (jsessionid, xsrf_token) using cached auth
+        2. Obtaining SDWAN Manager session data (jsessionid, xsrf_token) using
+           cached auth
         3. Creating and storing an SDWAN Manager client for use in verification methods
 
         The session data is obtained through the SDWANManagerAuth utility which
@@ -84,12 +92,14 @@ class SDWANManagerTestBase(NACTestBase):  # type: ignore[misc]
         self.client = self.get_sdwan_manager_client()
 
     def get_sdwan_manager_client(self) -> httpx.AsyncClient:
-        """Get an httpx async client configured for SDWAN Manager with response tracking.
+        """Get an httpx async client configured for SDWAN Manager.
+
+        Configured with response tracking.
 
-        Creates an HTTP client specifically configured for SDWAN Manager API communication
-        with session headers, base URL, and automatic response tracking for HTML
-        report generation. The client is wrapped to capture all API interactions
-        for detailed test reporting.
+        Creates an HTTP client specifically configured for SDWAN Manager API
+        communication with session headers, base URL, and automatic response
+        tracking for HTML report generation. The client is wrapped to capture all
+        API interactions for detailed test reporting.
 
         The client includes:
         - JSESSIONID cookie in all requests (via Cookie header)
@@ -98,9 +108,9 @@ class SDWANManagerTestBase(NACTestBase):  # type: ignore[misc]
         - Automatic API call tracking for reporting
 
         Returns:
-            httpx.AsyncClient: Configured client with SDWAN Manager session data, base URL,
-                and wrapped for automatic API call tracking. The client has SSL
-                verification disabled for lab environment compatibility.
+            httpx.AsyncClient: Configured client with SDWAN Manager session data,
+                base URL, and wrapped for automatic API call tracking. The client
+                has SSL verification disabled for lab environment compatibility.
 
         Note:
             SSL verification is disabled (verify=False) to support lab environments