Metadata-Version: 2.1
Name: byteblower-test-cases-rfc-2544
Version: 1.0.0b5
Summary: Perform throughput test based on RFC 2544 using ByteBlower.
Keywords: ByteBlower,network test,traffic test,test case,throughput,RFC 2544
Author-email: ByteBlower Development Team <support.byteblower@excentis.com>
Maintainer-email: Abdennour Rachedi <abdennour.rachedi@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 :: Other/Proprietary License
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.1.0
Requires-Dist: jinja2
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-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: RFC 2544 Throughput
*****************************************

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

This package contains an implementation of the `RFC 2544`_ Throughput
Test using the `ByteBlower Test Framework`_.

.. _RFC 2544: https://www.ietf.org/rfc/rfc2544.txt
.. _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

A throughput test aims to measure, under given circumstances,
the highest throughput the DUT can handle correctly without exceeding a given
threshold of frame loss (theoretically, this threshold is 0).

This ByteBlower RFC 2544 throughput test case allows you to:

#. Run throughput tests based on RFC 2544
#. Collect & Analyse statistics
#. Generate HTML & JSON reports

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

.. _Test Case\: RFC 2544 Throughput: https://api.byteblower.com/test-framework/latest/test-cases/rfc-2544/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.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**
   ``./env/bin/activate``.

   .. code-block:: shell

      python3 -m venv --clear env
      . ./env/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 env
      & ".\env\Scripts\activate.ps1"
      python -m pip install -U pip build

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

To install the ByteBlower RFC 2544 throughput 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

      . ./env/bin/activate

#. On Windows systems using PowerShell:

   .. code-block:: shell

      ./env/Scripts/activate.ps1

Then, run:

.. code-block:: shell

   pip install -U byteblower-test-cases-rfc-2544

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_case.rfc_2544 --help

#. As a command-line script:

   .. code-block:: shell

      # To get help for the command-line arguments:
      byteblower-test-cases-rfc-2544-throughput --help

To run the ByteBlower RFC 2544 throughput test case, you should first provide
your test configuration, or copy this `Configuration file example`_ to
``rfc_2544.json`` file you create in your working directory. Make sure to
update the example configuration to your actual setup configuration
(ByteBlower server host name or IP, source and destination ports)

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

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

   .. code-block:: shell

      # Optional: create rfc_2544.json, then copy the configuration to it
      touch rfc_2544.json
      # Create reports folder to store HTML/JSON files
      mkdir reports
      # Run test
      byteblower-test-cases-rfc-2544-throughput --report-path reports

#. On Windows systems using PowerShell:

   .. code-block:: shell

      # Optional: create rfc_2544.json, then copy the configuration to it
      New-Item rfc_2544.json
      # Create reports folder to store HTML/JSON files
      md reports
      # Run test
      byteblower-test-cases-rfc-2544-throughput --report-path reports

Integrated
----------

.. code-block:: python

   from byteblower.test_case.rfc_2544 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 RFC 2544 throughput test:
   run(test_config, report_path=report_path, report_prefix=report_prefix)


Configuration file example
--------------------------

.. code-block:: json

   {
       "server": "byteblower-server.com.",
       "source": {
           "name": "Source",
           "interface": "nontrunk-1",
           "ipv4": "192.168.5.2",
           "netmask": "255.255.255.0",
           "gateway": "192.168.5.254"
       },
       "destination": {
           "name": "Destination",
           "interface": "trunk-1",
           "ipv4": "dhcp",
           "nat": true
       },
       "duration": 60,
       "max_iterations": 25,
       "frame_configs": [
           {
               "size": 60,
               "initial_bitrate": 3e8,
               "tolerated_frame_loss": 1e-4,
               "expected_bitrate": 1.7e8,
               "accuracy": 1e3
           },
           {
               "size": 124,
               "initial_bitrate": 6e8,
               "tolerated_frame_loss": 1e-3,
               "expected_bitrate": 4.5e8,
               "accuracy": 1e4
           },
           {
               "size": 252,
               "initial_bitrate": 7e8,
               "tolerated_frame_loss": 1e-2,
               "expected_bitrate": 6.5e8,
               "accuracy": 1e5
           }
       ]
   }

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

.. _Configuration file: https://api.byteblower.com/test-framework/latest/test-cases/rfc-2544/config_file.html

