nac-test-pyats-common 0.1.1__tar.gz → 0.2.0__tar.gz

{nac_test_pyats_common-0.1.1 → nac_test_pyats_common-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nac-test-pyats-common
-Version: 0.1.1
+Version: 0.2.0
 Summary: Architecture adapters for Network as Code (NaC) PyATS testing - auth classes, test base classes, and device resolvers
 Project-URL: Homepage, https://github.com/netascode/nac-test-pyats-common
 Project-URL: Documentation, https://github.com/netascode/nac-test-pyats-common

{nac_test_pyats_common-0.1.1 → nac_test_pyats_common-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nac-test-pyats-common"
-version = "0.1.1"
+version = "0.2.0"
 description = "Architecture adapters for Network as Code (NaC) PyATS testing - auth classes, test base classes, and device resolvers"
 readme = "README.md"
 requires-python = ">=3.10"

{nac_test_pyats_common-0.1.1 → nac_test_pyats_common-0.2.0}/src/nac_test_pyats_common/__init__.py

@@ -29,7 +29,12 @@ __version__ = "1.0.0"
 
 # Public API - Import from subpackages
 from nac_test_pyats_common.aci import APICAuth, APICTestBase
-from nac_test_pyats_common.catc import CatalystCenterAuth, CatalystCenterTestBase
+from nac_test_pyats_common.catc import (
+    CatalystCenterAuth,
+    CatalystCenterDeviceResolver,
+    CatalystCenterSSHTestBase,
+    CatalystCenterTestBase,
+)
 from nac_test_pyats_common.sdwan import (
     SDWANDeviceResolver,
     SDWANManagerAuth,
@@ -49,4 +54,6 @@ __all__ = [
     # Catalyst Center
     "CatalystCenterAuth",
     "CatalystCenterTestBase",
+    "CatalystCenterSSHTestBase",
+    "CatalystCenterDeviceResolver",
 ]

nac_test_pyats_common-0.2.0/src/nac_test_pyats_common/catc/__init__.py

@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2025 Daniel Schmidt
+
+"""Catalyst Center adapter module for NAC PyATS testing.
+
+This module provides Catalyst Center-specific authentication, test base classes, and
+device resolver implementations for use with the nac-test framework. It includes support
+for both Catalyst Center API testing and SSH-based device-to-device (D2D) testing.
+
+Classes:
+    CatalystCenterAuth: Token-based authentication with automatic endpoint
+        detection.
+    CatalystCenterTestBase: Base class for Catalyst Center API tests with
+        tracking.
+    CatalystCenterSSHTestBase: Base class for Catalyst Center SSH/D2D tests
+        with device inventory.
+    CatalystCenterDeviceResolver: Resolves device information from the
+        Catalyst Center data model.
+
+Example:
+    For Catalyst Center API testing:
+
+    >>> from nac_test_pyats_common.catc import CatalystCenterTestBase
+    >>>
+    >>> class VerifyNetworkDevices(CatalystCenterTestBase):
+    ...     async def get_items_to_verify(self):
+    ...         return ['device-uuid-1', 'device-uuid-2']
+    ...
+    ...     async def verify_item(self, item):
+    ...         response = await self.client.get(
+    ...             f"/dna/intent/api/v1/network-device/{item}"
+    ...         )
+    ...         return response.status_code == 200
+
+    For SSH/D2D testing:
+
+    >>> from nac_test_pyats_common.catc import CatalystCenterSSHTestBase
+    >>>
+    >>> class VerifyInterfaceStatus(CatalystCenterSSHTestBase):
+    ...     @aetest.test
+    ...     def verify_interfaces(self, steps, device):
+    ...         # SSH-based verification
+    ...         pass
+"""
+
+from .api_test_base import CatalystCenterTestBase
+from .auth import CatalystCenterAuth
+from .device_resolver import CatalystCenterDeviceResolver
+from .ssh_test_base import CatalystCenterSSHTestBase
+
+__all__ = [
+    "CatalystCenterAuth",
+    "CatalystCenterTestBase",
+    "CatalystCenterSSHTestBase",
+    "CatalystCenterDeviceResolver",
+]

nac_test_pyats_common-0.2.0/src/nac_test_pyats_common/catc/device_resolver.py

@@ -0,0 +1,164 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2025 Daniel Schmidt
+
+"""Catalyst Center-specific device resolver for parsing the NAC data model.
+
+This module provides the CatalystCenterDeviceResolver class, which extends
+BaseDeviceResolver to implement Catalyst Center schema navigation for D2D testing.
+"""
+
+import logging
+from typing import Any
+
+from nac_test_pyats_common.common import BaseDeviceResolver
+from nac_test_pyats_common.iosxe.registry import register_iosxe_resolver
+
+logger = logging.getLogger(__name__)
+
+
+@register_iosxe_resolver("CC")
+class CatalystCenterDeviceResolver(BaseDeviceResolver):
+    """Catalyst Center device resolver for D2D testing.
+
+    Navigates the Catalyst Center NAC schema (catalyst_center.inventory.devices[])
+    to extract device information for SSH testing.
+
+    Schema structure:
+        catalyst_center:
+          inventory:
+            devices:
+              - name: P3-BN1
+                fqdn_name: P3-BN1.cisco.eu
+                device_ip: 192.168.38.1
+                pid: C9300-24P
+                state: PROVISION
+                device_role: ACCESS
+                site: Global/MAX_AREA/MAX_BUILDING
+
+    Credentials:
+        Uses IOSXE_USERNAME and IOSXE_PASSWORD environment variables
+        for SSH access to managed IOS-XE devices.
+
+    Example:
+        >>> resolver = CatalystCenterDeviceResolver(data_model)
+        >>> devices = resolver.get_resolved_inventory()
+        >>> for device in devices:
+        ...     print(f"{device['hostname']}: {device['host']}")
+    """
+
+    def get_architecture_name(self) -> str:
+        """Return 'catalyst_center' as the architecture identifier.
+
+        Returns:
+            Architecture name used in logging and error messages.
+        """
+        return "catalyst_center"
+
+    def get_schema_root_key(self) -> str:
+        """Return 'catalyst_center' as the root key in the data model.
+
+        Returns:
+            Root key used when navigating the schema.
+        """
+        return "catalyst_center"
+
+    def navigate_to_devices(self) -> list[dict[str, Any]]:
+        """Navigate Catalyst Center schema: catalyst_center.inventory.devices[].
+
+        Traverses the Catalyst Center data model structure to find all
+        managed devices in the inventory.
+
+        Returns:
+            List of device dictionaries from the inventory.
+        """
+        devices: list[dict[str, Any]] = []
+        cc_data = self.data_model.get("catalyst_center", {})
+        inventory = cc_data.get("inventory", {})
+        devices.extend(inventory.get("devices", []))
+        return devices
+
+    def validate_device_data(self, device_data: dict[str, Any]) -> None:
+        """Validate device state before extraction.
+
+        Skip devices with INIT or PNP states as they are not fully provisioned.
+
+        Args:
+            device_data: Device data dictionary from the data model.
+
+        Raises:
+            ValueError: If the device has an unsupported state (INIT, PNP).
+        """
+        state = device_data.get("state", "").upper()
+        if state in ("INIT", "PNP"):
+            raise ValueError(
+                f"Device has unsupported state '{state}' "
+                "(devices in INIT or PNP state are not fully provisioned)"
+            )
+
+    def extract_hostname(self, device_data: dict[str, Any]) -> str:
+        """Extract hostname from the 'name' field.
+
+        Uses the device name as the hostname for SSH connections.
+
+        Args:
+            device_data: Device data dictionary from the data model.
+
+        Returns:
+            Device hostname string.
+        """
+        name = device_data.get("name")
+        if not name:
+            raise ValueError("Device missing 'name' field")
+        return str(name)
+
+    def extract_host_ip(self, device_data: dict[str, Any]) -> str:
+        """Extract management IP from device_ip field.
+
+        Reads the device_ip field directly from the device data.
+        Handles CIDR notation if present (e.g., "10.1.1.100/32" -> "10.1.1.100").
+
+        Args:
+            device_data: Device data dictionary from the data model.
+
+        Returns:
+            IP address string without CIDR notation (e.g., "192.168.38.1").
+
+        Raises:
+            ValueError: If device_ip field is not found.
+        """
+        device_ip = device_data.get("device_ip")
+        if not device_ip:
+            raise ValueError(
+                "Device missing 'device_ip' field. "
+                "Ensure device_ip is configured in the inventory."
+            )
+
+        ip_value = str(device_ip)
+
+        # Strip CIDR notation if present
+        if "/" in ip_value:
+            ip_value = ip_value.split("/")[0]
+
+        return ip_value
+
+    def extract_os_type(self, device_data: dict[str, Any]) -> str:
+        """Return 'iosxe' as all managed devices are IOS-XE based.
+
+        Args:
+            device_data: Device data dictionary (unused, OS is hardcoded).
+
+        Returns:
+            Always returns 'iosxe'.
+        """
+        return "iosxe"
+
+    def get_credential_env_vars(self) -> tuple[str, str]:
+        """Return IOS-XE credential env vars for managed devices.
+
+        Catalyst Center D2D tests connect to IOS-XE devices,
+        NOT the Catalyst Center controller.
+
+        Returns:
+            Tuple of (username_env_var, password_env_var).
+        """
+        return ("IOSXE_USERNAME", "IOSXE_PASSWORD")

nac_test_pyats_common-0.2.0/src/nac_test_pyats_common/catc/ssh_test_base.py

@@ -0,0 +1,115 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2025 Daniel Schmidt
+
+"""Catalyst Center specific base test class for SSH/Direct-to-Device testing.
+
+This module provides the CatalystCenterSSHTestBase class, which extends the generic
+SSHTestBase to add Catalyst Center-specific functionality for device-to-device (D2D)
+testing.
+
+The class delegates device inventory resolution to CatalystCenterDeviceResolver, which
+handles all Catalyst Center schema navigation and credential injection.
+
+Credentials:
+    Catalyst Center D2D tests connect to IOS-XE devices managed by Catalyst Center,
+    NOT the Catalyst Center controller. Set these environment variables:
+    - IOSXE_USERNAME: SSH username for managed devices
+    - IOSXE_PASSWORD: SSH password for managed devices
+"""
+
+import logging
+import os
+from typing import Any
+
+from nac_test.pyats_core.common.ssh_base_test import (
+    SSHTestBase,  # type: ignore[import-untyped]
+)
+
+from .device_resolver import CatalystCenterDeviceResolver
+
+logger = logging.getLogger(__name__)
+
+
+class CatalystCenterSSHTestBase(SSHTestBase):  # type: ignore[misc]
+    """Catalyst Center-specific base test class for SSH/D2D testing.
+
+    This class extends SSHTestBase and implements the contract required by
+    nac-test's SSH execution engine. Device inventory resolution is fully
+    delegated to CatalystCenterDeviceResolver.
+
+    Credentials:
+        Catalyst Center D2D tests require IOSXE_USERNAME and IOSXE_PASSWORD
+        environment variables (NOT CC_* which are for the controller).
+
+    Example:
+        class MyCatalystCenterSSHTest(CatalystCenterSSHTestBase):
+            @aetest.test
+            def verify_device_connectivity(self, steps, device):
+                # SSH-based verification logic here
+                pass
+    """
+
+    # Class-level storage for the last resolver instance
+    # This allows nac-test to access skipped_devices after calling
+    # get_ssh_device_inventory()
+    _last_resolver: "CatalystCenterDeviceResolver | None" = None
+
+    @classmethod
+    def get_ssh_device_inventory(
+        cls, data_model: dict[str, Any]
+    ) -> list[dict[str, Any]]:
+        """Parse the Catalyst Center data model to retrieve the device inventory.
+
+        This method is the entry point called by nac-test's orchestrator.
+        All device inventory resolution is delegated to CatalystCenterDeviceResolver,
+        which handles:
+        - Schema navigation (catalyst_center.inventory.devices[])
+        - Device metadata extraction (name, device_ip, etc.)
+        - Credential injection (IOSXE_USERNAME, IOSXE_PASSWORD)
+
+        After calling this method, access cls._last_resolver.skipped_devices
+        to get information about devices that failed resolution.
+
+        Args:
+            data_model: The merged data model from nac-test containing all
+                configuration data with resolved variables.
+
+        Returns:
+            List of device dictionaries, each containing:
+            - hostname (str): Device hostname
+            - host (str): Management IP address for SSH connection
+            - os (str): Operating system type (e.g., "iosxe")
+            - username (str): SSH username from IOSXE_USERNAME
+            - password (str): SSH password from IOSXE_PASSWORD
+            - device_id (str): Device identifier (name)
+
+        Raises:
+            ValueError: If IOSXE_USERNAME or IOSXE_PASSWORD env vars are not set.
+        """
+        logger.info(
+            "CatalystCenterSSHTestBase: Resolving device inventory via "
+            "CatalystCenterDeviceResolver"
+        )
+
+        cls._last_resolver = CatalystCenterDeviceResolver(data_model)
+        return cls._last_resolver.get_resolved_inventory()
+
+    def get_device_credentials(self, device: dict[str, Any]) -> dict[str, str | None]:
+        """Get Catalyst Center managed device SSH credentials from env vars.
+
+        Catalyst Center D2D tests connect to IOS-XE devices managed by
+        Catalyst Center, NOT the Catalyst Center controller. Use IOSXE_*
+        environment variables.
+
+        Args:
+            device: Device dictionary (not used - all devices share credentials).
+
+        Returns:
+            Dictionary containing:
+            - username (str | None): SSH username from IOSXE_USERNAME
+            - password (str | None): SSH password from IOSXE_PASSWORD
+        """
+        return {
+            "username": os.environ.get("IOSXE_USERNAME"),
+            "password": os.environ.get("IOSXE_PASSWORD"),
+        }