pyATS AEreport

Common errors

• ssh: connect to host <ip_address> port 22: Connection refused

  cause The pyATS framework, via Unicon, attempted to establish an SSH connection to a device specified in the testbed file, but the device actively refused the connection. This can be due to incorrect IP, firewall rules, SSH service not running, or incorrect port.
  fix Verify the device's IP address and SSH port in the testbed file. Ensure the device is reachable from the pyATS host, its SSH server is running, and no firewall is blocking the connection. Use `dev.connect(log_stdout=True)` in an interactive Python session to get verbose SSH output for debugging.

• TypeError: 'NoneType' object is not iterable (e.g., when calling testbed.parse(<command>) after a connection failure)

  cause This error typically occurs when a test script attempts to perform operations (like parsing command output) on a device object that failed to connect, resulting in a `NoneType` object where a connected device object was expected.
  fix Implement checks in your test script to ensure a device is connected before attempting operations on it. For example, `if device.is_connected(): ...` or gracefully handle connection errors to remove disconnected devices from further operations.

• pyats version check reports 'version conflict' or similar errors (e.g., with Jinja2)

  cause Dependency conflicts can arise when different pyATS components or other installed packages require conflicting versions of shared libraries, such as Jinja2.
  fix Always use a dedicated Python virtual environment for pyATS installations to isolate its dependencies. If conflicts occur, try reinstalling pyATS with `pip install 'pyats[full]' --upgrade` within a fresh virtual environment.

Warnings

• breaking The `pyats.templates` and `pyats.examples` packages have been completely removed. Templating is now handled via the `pyats create` command, and examples are moved to a dedicated GitHub repository (`CiscoTestAutomation/examples`).
  Fix: Use `pyats create project` for new projects and refer to the `CiscoTestAutomation/examples` GitHub repository for example scripts.
• gotcha pyATS (and consequently AEreport) does not officially support Windows platforms. It is designed for Linux and Mac operating systems.
  Fix: Run pyATS and AEreport on a supported Linux or Mac environment, or use a Docker container provided by Cisco DevNet.
• gotcha Inconsistent test environments (OS versions, network configurations, hardware) can lead to erratic and misleading test results, undermining the reliability of AEreport's output.
  Fix: Standardize your test environments to closely mimic production as much as possible to ensure reliable and meaningful test outcomes. Use virtual environments.

Install

• pip install pyats.aereport Install only AEreport
• pip install 'pyats[full]' Install full pyATS (includes AEreport)

Imports

• aereport

  import pyats.aereport

  While 'pyats.aereport' can be imported, its functionality is typically integrated and managed by the 'pyats' runtime (e.g., 'easypy') rather than direct end-user class instantiation.
• aetest

  from pyats import aetest

  AEreport processes results from pyATS AEtest runs, making AEtest a common companion import for defining tests.

Quickstart

This quickstart demonstrates a basic pyATS AEtest script that, when executed, implicitly uses pyATS AEreport to collect and format test results. The `pyats logs view --latest` command can then be used in the terminal to open the generated HTML report in a web browser, showcasing AEreport's output.

import os
import logging
from pyats import aetest
from genie.testbed import load

# Configure logging for better visibility
logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO)

# Define a simple pyATS AEtest script
class CommonSetup(aetest.CommonSetup):
    @aetest.subsection
    def connect_to_devices(self, testbed):
        try:
            testbed.connect()
            logger.info("Successfully connected to devices.")
        except Exception as e:
            logger.error(f"Failed to connect to one or more devices: {e}")

class MyTestcase(aetest.Testcase):
    @aetest.test
    def verify_connectivity(self, testbed):
        for device in testbed.devices:
            if device.is_connected():
                self.passed(f"Device {device.name} is connected.")
            else:
                self.failed(f"Device {device.name} is NOT connected.")

class CommonCleanup(aetest.CommonCleanup):
    @aetest.subsection
    def disconnect_from_devices(self, testbed):
        for device in testbed.devices:
            if device.is_connected():
                device.disconnect()
                logger.info(f"Disconnected from device {device.name}.")

if __name__ == '__main__':
    # Example Testbed file content (save as 'testbed.yaml')
    # devices:
    #   router1:
    #     connections:
    #       cli:
    #         class: unicon.Unicon
    #         protocol: ssh
    #         ip: 10.0.0.1 # Replace with your device IP
    #     credentials:
    #       default:
    #         username: cisco
    #         password: cisco # Use environment variable or pyats secret for production

    # Create a dummy testbed.yaml for demonstration if it doesn't exist
    testbed_content = """
devices:
  loopback_device:
    type: linux
    connections:
      defaults:
        class: unicon.Unicon
        protocol: ssh
        # For a truly runnable example without a real device, mock or avoid connection.
        # This example assumes a simple mock or a non-connect test for quick demo.
        # In a real scenario, you'd point to a reachable device or a mocked one.
    credentials:
      default:
        username: {}
        password: {}
""".format(os.environ.get('TEST_USERNAME', 'mockuser'), os.environ.get('TEST_PASSWORD', 'mockpass'))

    with open('testbed.yaml', 'w') as f:
        f.write(testbed_content)

    # Load the testbed (dummy for this example)
    testbed = load('testbed.yaml')

    # Run the AEtest job. AEreport automatically collects results.
    aetest.main(testbed=testbed, ) # You would typically use pyats run job <script.py> for reporting
    
    # To view the generated report, run in your terminal:
    # pyats logs view --latest