Metadata-Version: 2.3
Name: byteblower-test-cases-docsis-atp
Version: 1.0.0
Summary: Perform traffic tests for DOCSIS 4.0 ATP using ByteBlower.
Keywords: ByteBlower,network test,traffic test,test case,Docsis-atp
Author-email: ByteBlower Development Team <support.byteblower@excentis.com>
Maintainer-email: Hamza Malkawi <hamza.malkawi@excentis.com>, Taimour Kasabi <taimour.kasabi@excentis.com>, Tom Ghyselinck <tom.ghyselinck@excentis.com>
Requires-Python: >=3.7
Description-Content-Type: text/x-rst
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Telecommunications Industry
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Testing :: Acceptance
Classifier: Topic :: Software Development :: Testing :: Traffic Generation
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: byteblower-test-framework >=1.4.0
Requires-Dist: pandas >=0.24.2
Requires-Dist: jinja2 >=2.10.1
Requires-Dist: highcharts-excentis >=0.4.4
Requires-Dist: pre-commit ; extra == "dev"
Requires-Dist: yapf[pyproject] ; extra == "dev"
Requires-Dist: isort ; extra == "dev"
Requires-Dist: rstcheck[toml] ; extra == "dev"
Requires-Dist: doc8 ; extra == "dev"
Requires-Dist: Pygments ; extra == "dev"
Requires-Dist: pydocstyle[toml] ; extra == "dev"
Requires-Dist: toml ~=0.10.2 ; extra == "dev"
Requires-Dist: Sphinx >= 5.0 ; extra == "docs-dev"
Requires-Dist: sphinx-rtd-theme >=1.0 ; extra == "docs-dev"
Requires-Dist: sphinx-tabs >= 3.4 ; extra == "docs-dev"
Requires-Dist: sphinx-jsonschema >= 1.19 ; extra == "docs-dev"
Requires-Dist: importlib-metadata>=4.8.3 ; extra == "docs-dev" and ( python_version<'3.8')
Requires-Dist: rstcheck[sphinx, toml] ; extra == "docs-dev"
Requires-Dist: pylint[spelling] ; extra == "test"
Requires-Dist: pydocstyle[toml] ; extra == "test"
Requires-Dist: rstcheck[sphinx, toml] ; extra == "test"
Requires-Dist: mypy >=1.0.0 ; extra == "test"
Requires-Dist: pandas-stubs ; extra == "test"
Requires-Dist: types-simplejson ; extra == "test"
Requires-Dist: pytest >=6.0 ; extra == "test"
Requires-Dist: pytest-cov ; extra == "test"
Requires-Dist: pytest-pydocstyle ; extra == "test"
Requires-Dist: toml ~=0.10.2 ; extra == "test"
Project-URL: Documentation, https://api.byteblower.com/test-framework/latest/test-cases/docsis-atp/master_index.html
Project-URL: Examples, https://api.byteblower.com/test-framework/latest/test-cases/docsis-atp/examples/index.html
Project-URL: Homepage, https://www.byteblower.com
Project-URL: Support Portal, https://support.excentis.com
Provides-Extra: dev
Provides-Extra: docs-dev
Provides-Extra: test

************************************
ByteBlower Test Case: DOCSIS 4.0 ATP
************************************

Introduction
============

This package contains an implementation of the DOCSIS 4.0 ATP
Test using the `ByteBlower Test Framework`_.

.. _ByteBlower Test Framework: https://pypi.org/project/byteblower-test-framework/

.. footer::
   Copyright |copy| |year| - Excentis N.V.

.. |copy| unicode:: U+00A9 .. copyright sign
.. |year| date:: %Y

The goal of the test is to verify the DOCSIS PIE AQM behavior in the presence
and absence of LLD traffic, and evaluate the delay estimator.


DOCSIS 4.0 ATP introduction
============================
This ByteBlower MULPIv4 LL-04.40 Part test case allows you to:

#. Run tests based on MULPIv4 LL-04 ATP
#. Collect & Analyse statistics
#. Generate HTML report

For more detailed documentation, please have a look
at `Test Case: DOCSIS 4.0 ATP`_ in the ByteBlower API documentation.

.. _Test Case\: DOCSIS 4.0 ATP: https://api.byteblower.com/test-framework/latest/test-cases/docsis-atp/overview.html

Installation
============

Requirements
------------

* `ByteBlower Test Framework`_: ByteBlower |registered| is a traffic
  generator/analyser system for TCP/IP networks.
* Highcharts-excentis_: Used for generating graphs
* jinja2_: To create HTML reports

.. _Highcharts-excentis: https://pypi.org/project/highcharts-excentis/
.. |registered| unicode:: U+00AE .. registered sign
.. _jinja2: https://pypi.org/project/Jinja2/

Prepare runtime environment
---------------------------

We recommend managing the runtime environment in a Python virtual
environment. This guarantees proper separation of the system-wide
installed Python and pip packages.

Python
------

The ByteBlower Test Framework currently supports Python versions 3.7
up to 3.12.

Important: Working directory
----------------------------

All the following sections expect that you first moved to your working
directory where you want to run this project. You may also want to create
your configuration files under a sub-directory of your choice.

#. On Unix-based systems (Linux, WSL, macOS):

   .. code-block:: shell

      cd '/path/to/working/directory'

#. On Windows systems using PowerShell:

   .. code-block:: shell

      cd 'c:\path\to\working\directory'

Python virtual environment
--------------------------

Make sure to use the right Python version (>= 3.7, <= 3.11),
list all Python versions installed in your machine by running:

#. On Windows systems using PowerShell:

   .. code-block:: shell

      py --list

If no Python version is in the required range, you can download and install
Python 3.7 or above using your system package manager
or from https://www.python.org/ftp/python.

Prepare Python virtual environment: Create the virtual environment
and install/update ``pip`` and ``build``.

#. On Unix-based systems (Linux, WSL, macOS):

   **Note**: *Mind the leading* ``.`` *which means* **sourcing**
   ``./.venv/bin/activate``.

   .. code-block:: shell

      python3 -m venv --clear .venv
      . ./.venv/bin/activate
      pip install -U pip build

#. On Windows systems using PowerShell:

   **Note**: On Microsoft Windows, it may be required to enable the
   Activate.ps1 script by setting the execution policy for the user.
   You can do this by issuing the following PowerShell command:

   .. code-block:: shell

      Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

   See `About Execution Policies`_ for more information.

   Make sure to specify the python version you're using.
   For example, for Python 3.8:

   .. code-block:: shell

      py -3.8 -m venv --clear .venv
      & ".\.venv\Scripts\activate.ps1"
      python -m pip install -U pip build

   .. _About Execution Policies: https://go.microsoft.com/fwlink/?LinkID=135170

To install the ByteBlower DOCSIS 4.0 ATP test case and
its dependencies, first make sure that you have activated your
virtual environment:

#. On Unix-based systems (Linux, WSL, macOS):

   .. code-block:: shell

      . ./.venv/bin/activate

#. On Windows systems using PowerShell:

   .. code-block:: shell

      ./.venv/Scripts/activate.ps1

Then, run:

.. code-block:: shell

   pip install -U byteblower-test-cases-docsis-atp

Quick start
===========

Command-line interface
----------------------

After providing the appropriate test setup and frame configurations,
the test script can be run either as python module or as a command-line script.

For example (*to get help for the command-line arguments*):

#. As a python module:

   .. code-block:: shell

      # To get help for the command-line arguments:
      python -m byteblower.test_cases.docsis_atp.mulpi_v4_0.ll_04_40.part1 --help

#. As a command-line script:

   .. code-block:: shell

      # To get help for the command-line arguments:
      byteblower-test-cases-docsis-atp-mulpi-v4-0-ll-04-40-part1 --help

To run the ByteBlower DOCSIS 4.0 ATP test case,
you should first provide your test configuration file.

you can use the `Configuration example`_ as a reference. Make sure to
update the example configuration to your actual setup configuration
(ByteBlower server host name or IP, NSI and CPE ports)

``part1.json`` is the default configuration file name.
You can use the argument ``--config-file`` to specify your configuration file.


The reports will be stored under a subdirectory ``reports/``.

#. On Unix-based systems (Linux, WSL, macOS):

   .. code-block:: shell

      # Optional: create part1.json, then copy the configuration to it
      touch part1.json
      # Create reports folder to store HTML/JSON files
      mkdir reports
      # Run test
      byteblower-test-cases-docsis-atp-mulpi-v4-0-ll-04-40-part1 --report-path reports

#. On Windows systems using PowerShell:

   .. code-block:: shell

      # Optional: create part1.json, then copy the configuration to it
      New-Item part1.json
      # Create reports folder to store HTML/JSON files
      md reports
      # Run test
      byteblower-test-cases-docsis-atp-mulpi-v4-0-ll-04-40-part1 --report-path reports

Integrated
----------

High-level integration with manual interaction:

.. code-block:: python

   from byteblower.test_cases.docsis_atp.mulpi_v4_0.ll_04_40.part1 import run

   # Defining test configuration, report path and report file name prefix:
   test_config = {} # Here you should provide your test setup + frame(s') configuration(s)
   report_path = 'my-output-folder' # Optional: provide the path to the output folder, defaults to the current working directory
   report_prefix = 'my-dut-feature-test' # Optional: provide prefix of the output files, defaults to 'report'

   # Run the DOCSIS 4.0 ATP test:
   run(test_config, report_path=report_path, report_prefix=report_prefix)

High-level integration in user test scripts
and *optional* custom post-processing:

.. code-block:: python

   from byteblower.test_cases.docsis_atp.mulpi_v4_0.ll_04_40.part1 import (
       configure_traffic_endpoints,
       generate_report,
       run_procedure_1_1,
       run_procedure_1_2,
   )

   _TEST_CONFIG = {
       "server": "byteblower-server.example.com",
       "nsi": {
           "name": "NSI",
           "interface": "nontrunk-1",
           "mac": "00:ff:bb:00:00:11",
           "ipv4": "dhcp"
       },
       "cpe": {
           "name": "CPE",
           "interface": "trunk-1-1",
           "mac": "00:ff:bb:00:00:22",
           "ipv4": "dhcp",
           "nat": True
       }
   }

   # 1. Configure the test
   traffic_endpoints_configuration = configure_traffic_endpoints(_TEST_CONFIG)
   #    + Extract the traffic endpoints for the two test procedures
   server, nsi_config, cpe_config = traffic_endpoints_configuration

   # NOTE: At this point, prepare the CMTS and cable modems
   # for test procedure 1.1

   # 2. Run LL-04.40 Part 1, test Procedure 1.1
   proc_1_report_info = run_procedure_1_1(
       server,
       nsi_config,
       cpe_config,
       enable_capture=True,
       enable_sequence_numbers=True,
   )

   # NOTE: At this point, prepare the CMTS and cable modems
   # for test procedure 1.2

   # 3. Run LL-04.40 Part 1, test Procedure 1.2
   proc_2_report_info = run_procedure_1_2(
       server,
       nsi_config,
       cpe_config,
       enable_capture=True,
       enable_sequence_numbers=True,
   )

   # 4. Generate the (HTML) test report
   report_file_path = generate_report(
       proc_1_report_info,
       proc_2_report_info,
       report_path=Path.cwd(),
       report_prefix='my_report_prefix',
   )

   # 5. Extract captures and flow UDP ports for each test procedure
   #    To be used for further post-processing
   proc_1_capture_info = proc_1_report_info[2]
   proc_1_capture_file_path, proc_1_udp_dest_ports = proc_1_capture_info

   proc_2_capture_info = proc_2_report_info[2]
   proc_2_capture_file_path, proc_2_udp_dest_ports = proc_2_capture_info

Configuration example
---------------------

.. code-block:: json

   {
      "server": "byteblower-server.example.com",
      "nsi": {
         "name": "NSI",
         "interface": "nontrunk-1",
         "ipv4": "10.1.1.125",
         "netmask": "255.255.255.0",
         "gateway": "10.1.1.1"
      },
      "cpe": {
         "name": "CPE",
         "interface": "trunk-1-7",
         "ipv4": "dhcp",
         "nat": true
      }
   }

More detailed documentation is available in the `Configuration file`_ section
of the documentation.

.. _Configuration file: https://api.byteblower.com/test-framework/latest/test-cases/docsis-atp/config/index.html

