Installation & Quick start

Tags: Introduction

Installation

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

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:

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:

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

Install the ByteBlower Test Framework

First make sure that you have activated your virtual environment:

On Windows systems using PowerShell:

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

Now install (or update) the ByteBlower Test Framework:

pip install -U byteblower-test-framework

The ByteBlower Test Framework and its dependencieswill 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 one of these example scenarios to get started. Copy it to your working directory as byteblower_test_framework.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-framework

By default:

  • The configuration file (byteblower_test_framework.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 ByteBlower test framework can also be imported and used in Python as follows:

from byteblower_test_framework 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 traffic 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.