Installation & Quick start

Installation

Requirements

Prepare runtime environment

Python

The ByteBlower Test Framework currently supports Python versions >= 3.7.

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

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

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

Prepare Python virtual environment: Create the virtual environment and install/update pip and 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:

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

Install the ByteBlower TR-398 Airtime Fairness Test Case

First make sure that you have activated your virtual environment:

On Windows systems using PowerShell:

& ".\.venv\Scripts\activate.ps1"

Then install (or update) the TR-398 Airtime Fairness test case and its dependencies:

pip install -U byteblower-test-cases-tr-398

The latest version from the TR-398 Airtime Fairness test case and its dependencies will now be installed from PyPI.

Example test scenario

To run your test using the command-line interface, define your test scenario in a file in JSON format.

Use the example scenario to get started. Copy it to your working directory as tr_398.json:

Note

Make sure to update the example configuration to your actual test setup:

  • ByteBlower server host name or IP: server entry

  • ByteBlower Port configuration: interface and ipv4 / ipv6 / gateway / netmask / nat entries.

and for the Endpoint example, also change:

  • Meeting Point host name or IP: meeting_point entry

  • ByteBlower Endpoint configuration: uuid and ipv4 / ipv6 entries.

Run a test

The traffic test scenario can be run via command-line interface (either as a script or Python module), or integrated in your own Python script.

Command-line interface

Run a test with default input/output parameters

byteblower-test-cases-tr-398-airtime-fairness

By default:

  • The configuration file (tr_398.json) will be loaded from the current directory.

  • The resulting reports will also be saved into the current directory.

Take a look here for more details on using the Command-line interface.

From Python

The TR-398 Airtime Fairness test case can also be imported and used in Python as follows:

from byteblower.test_cases.tr_398.airtime_fairness import run

# Show documentation
help(run)

# Defining test configuration, report path and report file name prefix:

# Here you provide your test setup (ByteBlower server, ports, flows, ...),
# or load it from a JSON file
test_config = {}

# Optional: provide the path to the output folder, defaults to the current
# working directory
report_path = 'my-output-folder'

# Optional: provide prefix of the output files, defaults to 'report'
report_prefix = 'my-dut-feature-test'

# Run the TR-398 Airtime Fairness test:
run(test_config, report_path=report_path, report_prefix=report_prefix)

Define your own test scenario

Congratulations! You just ran your first traffic tests.

You want to define your own test scenarios? Great!

Have a look at Test scenario definition for a complete overview of the configuration format.