{"id":7543,"library":"pyats-reporter","title":"pyATS Reporter","description":"pyATS Reporter is a sub-component of the broader pyATS (Python Automated Test System) ecosystem, specializing in result collection and reporting for network automation tests. The pyATS framework itself is an end-to-end testing solution developed by Cisco Systems Inc., designed for data-driven, reusable, and scalable testing, suitable for Agile development iterations. The library is actively maintained with frequent updates, with the current version being 26.3, and requires Python 3.8 or higher.","status":"active","version":"26.3","language":"en","source_language":"en","source_url":"https://github.com/CiscoTestAutomation/pyats","tags":["network automation","testing","reporting","cisco","pyats","aetest","easypy"],"install":[{"cmd":"pip install pyats-reporter","lang":"bash","label":"Install only reporter component"},{"cmd":"pip install pyats[full]","lang":"bash","label":"Install full pyATS suite (recommended for most users)"}],"dependencies":[{"reason":"pyats-reporter is a sub-component of the pyATS framework and is typically used within a pyATS test automation setup.","package":"pyats","optional":false}],"imports":[{"note":"While `pyats.reporter` is a module, direct instantiation of `Reporter` for custom reporting is less common in typical usage. Most users interact with reporting through the `pyats run job` command or `pyats.aetest`/`pyats.easypy` framework, which implicitly use the reporter functionality. For specific advanced custom reporting, classes within `pyats.reporter.reporter` might be imported, but standard examples are scarce.","symbol":"Reporter","correct":"from pyats.reporter import Reporter"}],"quickstart":{"code":"import os\nimport time\nfrom pyats import aetest\nfrom pyats.topology import loader\n\n# Create a dummy testbed.yaml file for demonstration\nwith open('testbed.yaml', 'w') as f:\n    f.write('''\n# Sample Testbed for pyATS Reporter Quickstart\ntestbed:\n  name: my_testbed\n  credentials:\n    default:\n      username: admin\n      password: ${PYATS_TESTBED_PASSWORD}\n  devices:\n    R1:\n      type: router\n      os: iosxe\n      connections:\n        cli:\n          protocol: ssh\n          ip: 10.1.1.1 # Placeholder IP, replace with a reachable device or mock\n''')\n\n# Create a simple AEtest job file\nwith open('my_test_job.py', 'w') as f:\n    f.write('''\nfrom pyats import aetest\nfrom pyats.topology import loader\n\nclass CommonSetup(aetest.CommonSetup):\n    @aetest.subsection\n    def connect_to_devices(self, testbed):\n        aetest.loop.mark(self.parent.testcases.test_basic_connectivity, device=testbed.devices.values())\n        for device in testbed.devices.values():\n            self.parent.parameters.update(device=device)\n            print(f\"Attempting to connect to {device.name}\")\n            # In a real scenario, this would attempt a connection.\n            # For quickstart, we'll simulate success.\n            # device.connect()\n            print(f\"Simulated connection to {device.name} successful.\")\n\nclass TestBasicConnectivity(aetest.Testcase):\n    @aetest.test\n    def test_ping_loopback(self, device):\n        print(f\"Testing connectivity for {device.name}\")\n        # In a real scenario, this would execute a command like `device.ping('1.1.1.1')`\n        # For quickstart, we'll simulate a passing test.\n        if device.name == 'R1':\n            self.passed(f\"Simulated ping successful on {device.name}\")\n        else:\n            self.failed(f\"Simulated ping failed on {device.name}\")\n\nclass CommonCleanup(aetest.CommonCleanup):\n    @aetest.subsection\n    def disconnect_from_devices(self, testbed):\n        for device in testbed.devices.values():\n            print(f\"Simulated disconnection from {device.name}\")\n            # In a real scenario: device.disconnect()\n''')\n\n# Set a dummy password for the quickstart's testbed if not already set\nos.environ['PYATS_TESTBED_PASSWORD'] = os.environ.get('PYATS_TESTBED_PASSWORD', 'your_password_here')\n\nprint(\"Running pyATS job... This will generate a report.\")\n# To run the job and generate a report, use the pyats CLI command\n# In a real environment, you'd run this from your terminal:\n# pyats run job my_test_job.py --testbed-file testbed.yaml\n# For this quickstart, we'll just demonstrate the files are set up.\n\nprint(\"A testbed.yaml and my_test_job.py have been created.\")\nprint(\"To run the test and generate a report, execute in your terminal:\")\nprint(\"  pyats run job my_test_job.py --testbed-file testbed.yaml\")\nprint(\"After running, view the report with:\")\nprint(\"  pyats logs view\")\nprint(\"Cleanup: Remove 'testbed.yaml' and 'my_test_job.py' if desired.\")","lang":"python","description":"The pyATS Reporter primarily functions as part of a larger pyATS test execution. This quickstart demonstrates how to set up and run a minimal pyATS job, which will automatically generate a report using `pyats-reporter` capabilities. The output can then be viewed through the `pyats logs view` command-line tool. A placeholder IP is used; replace with a reachable device or use pyATS mocking for actual execution without a physical device. Make sure to set `PYATS_TESTBED_PASSWORD` environment variable for the testbed credentials if running against a real device."},"warnings":[{"fix":"Upgrade your Python environment to version 3.8, 3.9, 3.10, 3.11, 3.12, or 3.13. pyATS officially supports these versions.","message":"Python 3.6 reached End-of-Life. pyATS and pyats-reporter no longer support Python 3.6 after April 2022. Users must upgrade to Python 3.8 or newer.","severity":"breaking","affected_versions":"<=22.3"},{"fix":"Use pyATS on a Linux or macOS environment, or within a Linux-based virtual machine or Docker container on Windows.","message":"pyATS, including pyats-reporter, does not officially support Windows operating systems. It is designed for Linux and macOS environments.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure strict YAML formatting. The 'name' or 'alias' for a device in the testbed file must exactly match the device's configured hostname. For credentials, use environment variables (`%ENV{VAR_NAME}`) instead of hardcoding.","message":"Testbed YAML files are strict. Common mistakes include incorrect indentation, mismatching device names in the YAML with the actual device hostnames, or improper credential handling.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If you relied on `reporter.log` always being generated, ensure you run your `pyats run job` commands with the `-v` flag for verbose output.","message":"As of pyATS 22.3, ReporterServer was modified to only generate `reporter.log` when running in verbose mode with the `-v` option.","severity":"deprecated","affected_versions":"Introduced in 22.3"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"First, verify basic network connectivity (ping, telnet/ssh). Then, double-check testbed file (IPs, credentials, OS/platform settings) and ensure SSH access is fully functional and not blocked by firewalls.","cause":"This usually indicates a connectivity issue (e.g., SSH unreachable, incorrect credentials, firewall blocking).","error":"Failed while bringing device to \"any\" state"},{"fix":"Always check the detailed logs generated by pyATS in the run directory (usually `archive/<timestamp>/<job_name>/log/`). Use `pyats logs view` to open the interactive HTML report, which provides comprehensive information on failures.","cause":"A generic error indicating a failure during job execution, which could be due to issues in the test script, testbed, or environment. The Reporter component will capture more specific details.","error":"ERROR: Command '['pyats', 'run', 'job', ...]']' failed with exit code 1. Check logs for details."},{"fix":"Quote the package name to prevent shell interpretation: `pip install 'pyats[full]'`.","cause":"This error occurs when using Zsh shell on macOS or Linux, as the `[` and `]` characters are treated as special characters for globbing.","error":"Command failed: pip install pyats[full]\nERROR: zsh: no matches found: pyats[full]"}]}