Metadata-Version: 2.1
Name: byteblower-test-cases-low-latency
Version: 1.2.2
Summary: Low Latency test case using ByteBlower.
Keywords: ByteBlower,network test,traffic test,test case,LLD,Low-Latency DOCSIS,L4S
Author-email: ByteBlower Development Team <support.byteblower@excentis.com>
Maintainer-email: Tom Ghyselinck <tom.ghyselinck@excentis.com>, Abdennour Rachedi <abdennour.rachedi@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.0.0,<2.0.0
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: rstcheck[sphinx,toml] ; extra == "docs-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-tags >= 0.3.1 ; extra == "docs-dev"
Requires-Dist: sphinx-design >= 0.5.0 ; 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: pylint[spelling] ; extra == "test"
Requires-Dist: pydocstyle[toml] ; extra == "test"
Requires-Dist: rstcheck[toml] ; 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
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: Traffic tests for low latency validation
**************************************************************

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

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

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

This package contains a test case to generate multiple types of traffic
patterns using the `ByteBlower Test Framework`_. The traffic patterns
are used to validate your network for low latency.

.. _ByteBlower Test Framework: https://pypi.org/project/byteblower-test-framework/
.. _ByteBlower Endpoint: https://www.excentis.com/products/byteblower-endpoint/

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

.. _Test Case\: Low Latency: https://api.byteblower.com/test-framework/latest/test-cases/low-latency/overview.html

Release notes
=============

What can this version bring to you?
See our exciting new and existing features below!

📢 **New since v1.2.0!** 📢
---------------------------

.. _Low Latency, Low Loss, and Scalable Throughput (L4S): https://datatracker.ietf.org/doc/html/rfc9330

It is with great pleasure that we announce our
new features of this test case!

- Support for `Low Latency, Low Loss, and Scalable Throughput (L4S)`_ on TCP

  - Run traffic tests on your L4S-enabled network!

📢 **New since v1.1.0!** 📢
---------------------------

It is with great pleasure that we announce our
new features of this test case!

- Integration of the **ByteBlower Endpoint**

  - *Wi-Fi and mobile testing* via the `ByteBlower Endpoint`_!

We also fixed some inconsistencies in the command-line interface and
configuration file:

- Command-line interface: Default search path for the configuration file
  is now the *current directory* instead of looking in an *examples*
  sub-directory. This makes it more convenient for the user and
  consistent with the CLI of the ByteBlower Test Framework.
- Command-line JSON configuration file: Deprecated ``napt_keep_alive``
  in favor of ``nat_keep_alive``. Done for naming consistency with the
  *NAT-discovery IPv4 ports* in ByteBlower Test Framework >= v1.2.0.
- Changed rate-limiting parameter in the flow ``"type": "http"`` to
  ``maximum_bitrate`` (in *bits per second*). It replaces ``rate_limit``
  which was in *Bytes per second*.

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

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

* `ByteBlower Test Framework`_: ByteBlower |registered| is a traffic
  generator/analyser system for TCP/IP networks.

.. |registered| unicode:: U+00AE .. registered sign

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.11.

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

      PS C:> 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 low latency validation 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-low-latency

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

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

After providing the appropriate test setup and flow 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.low_latency --help

#. As a command-line script:

   .. code-block:: shell

      # To get help for the command-line arguments:
      byteblower-test-cases-low-latency --help

For a quick start, you can run a simple test using the JSON configuration of
one of the example files below:

* Using `ByteBlower Ports scenario <https://api.byteblower.com/test-framework/json/test-cases/low-latency/port/low_latency.json>`_
* Using `ByteBlower Endpoint scenario <https://api.byteblower.com/test-framework/json/test-cases/low-latency/endpoint/low_latency.json>`_

Save you configuration in your working directory as ``low_latency.json``.
Make sure you change the ``"server"`` and ``"ports"`` configuration
according to the setup you want to run your test on.

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

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

The ``low_latency.json`` can be used then to run the test in the
command line interface using the following commands:

**Note**: *The reports will be stored under a subdirectory* ``reports/``.

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

   .. code-block:: shell

      # Optional: create low_latency.json, then copy the configuration to it
      touch low_latency.json
      # Create reports folder to store HTML/JSON files
      mkdir reports
      # Run test
      byteblower-test-case-low-latency --report-path reports

#. On Windows systems using PowerShell:

   .. code-block:: shell

      # Optional: create low_latency.json, then copy the configuration to it
      New-Item low_latency.json
      # Create reports folder to store HTML/JSON files
      md reports
      # Run test
      byteblower-test-case-low-latency --report-path reports

Integrated
----------

.. code-block:: python

   from byteblower.test_cases.low_latency 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 low latency validation test:
   run(test_config, report_path=report_path, report_prefix=report_prefix)

