byteblower-test-cases-low-latency 1.3.0

Low Latency test case using ByteBlower.

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.

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

Release notes

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

📢 New since v1.3.0! 📢

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

• Extended IPv6 support

  • Running traffic tests with IPv6 ports behind a firewall

  • Manual IPv6 address configuration

• Imix support in Scenario definition. Supported in frame blasting based flows:

  • UDP frame_blasting flow type

  • UDP dynamic_frame_blasting flow type

  • L4S l4s_frame_blasting flow type

• Documentation

  • Added notes regarding proper SSL setup for Python on macOS.

  • Provided details and examples for MAC address configuration in the documentation and the JSON schema.

  • Fixed mismatch in L4S example description and scenario definition file. It was also raising errors with the latest release of the ByteBlower API and ByteBlower Test Framework. Both ByteBlowerPort and Endpoint examples were affected.

• Fixed hitting Highcharts fair use policy rate limit when running many concurrent tests from different scripts (via ByteBlower Test Framework update).

• Fixed issue with setting KPIs on the GamingFlow.

• High-level integration interface: make run function re-usable in a single test script. Release the server objects so that conflicts in new test scenarios are minimized.

📢 New since v1.2.0! 📢

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 ® is a traffic generator/analyser system for TCP/IP networks.

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.

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

   cd '/path/to/working/directory'

2. On Windows systems using PowerShell:

   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:

1. On Windows systems using PowerShell:

   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.

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

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

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

2. 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:

   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:

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

To install the ByteBlower low latency validation test case and its dependencies, first make sure that you have activated your virtual environment:

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

   . ./.venv/bin/activate

   Note: For macOS: later on, when generating ByteBlower HTML reports, you might see SSL errors like:

   ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1129)
   urllib.error.URLError: <urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1131)>

   You can fix this by installing or updating the CA certificates for your Python version. In your activated Python virtual environment in a macOS Terminal, type (for example, for Python 3.12):

   open /Applications/Python\ 3.12/Install\ Certificates.command

2. On Windows systems using PowerShell:

   ./.venv/Scripts/activate.ps1

Then, run:

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

1. As a python module:

   # To get help for the command-line arguments:
   python -m byteblower.test_cases.low_latency --help

2. As a command-line script:

   # 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

• Using ByteBlower Endpoint scenario

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.

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

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

   # 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

2. On Windows systems using PowerShell:

   # 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

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)