byteblower-test-cases-low-latency 1.2.2
Low Latency test case using ByteBlower.
Requires Python: >=3.7
Keywords: ByteBlower, network test, traffic test, test case, LLD, Low-Latency DOCSIS, L4S

**************************************************************
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)