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

First make sure that you have activated your virtual environment:

On Windows systems using PowerShell:

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

Then install (or update) the MULPIv4 LL-04.40 Part 1 test case and its dependencies:

pip install -U byteblower-test-cases-docsis-atp

The latest version from the MULPIv4 LL-04.40 Part 1 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 part1.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.

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-docsis-atp-mulpi-v4-0-ll-04-40-part1

By default:

  • The configuration file (part1.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.

Integrated

The MULPIv4 LL-04.40 Part 1 test case can also be imported and used in Python as follows:

  1. High-level integration with manual interaction:

    from byteblower.test_cases.docsis_atp.mulpi_v4_0.ll_04_40.part1 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 DOCSIS 4.0 - MULPIv4 LL-04.40 Part 1 test:
run(test_config, report_path=report_path, report_prefix=report_prefix)

  2. High-level integration in user test scripts and optional custom post-processing:

    from byteblower.test_cases.docsis_atp.mulpi_v4_0.ll_04_40.part1 import (
    configure_traffic_endpoints,
    generate_report,
    run_procedure_1_1,
    run_procedure_1_2,
)

_TEST_CONFIG = {
    "server": "byteblower-server.example.com",
    "nsi": {
        "name": "NSI",
        "interface": "nontrunk-1",
        "mac": "00:ff:bb:00:00:11",
        "ipv4": "dhcp"
    },
    "cpe": {
        "name": "CPE",
        "interface": "trunk-1-1",
        "mac": "00:ff:bb:00:00:22",
        "ipv4": "dhcp",
        "nat": True
    }
}

# 1. Configure the test
traffic_endpoints_configuration = configure_traffic_endpoints(_TEST_CONFIG)
#    + Extract the traffic endpoints for the two test procedures
server, nsi_config, cpe_config = traffic_endpoints_configuration

# NOTE: At this point, prepare the CMTS and cable modems
# for test procedure 1.1

# 2. Run LL-04.40 Part 1, test Procedure 1.1
proc_1_report_info = run_procedure_1_1(
    server,
    nsi_config,
    cpe_config,
    enable_capture=True,
    enable_sequence_numbers=True,
)

# NOTE: At this point, prepare the CMTS and cable modems
# for test procedure 1.2

# 3. Run LL-04.40 Part 1, test Procedure 1.2
proc_2_report_info = run_procedure_1_2(
    server,
    nsi_config,
    cpe_config,
    enable_capture=True,
    enable_sequence_numbers=True,
)

# 4. Generate the (HTML) test report
report_file_path = generate_report(
    proc_1_report_info,
    proc_2_report_info,
    report_path=Path.cwd(),
    report_prefix='my_report_prefix',
)

# 5. Extract captures and flow UDP ports for each test procedure
#    To be used for further post-processing
proc_1_capture_info = proc_1_report_info[2]
proc_1_capture_file_path, proc_1_udp_dest_ports = proc_1_capture_info

proc_2_capture_info = proc_2_report_info[2]
proc_2_capture_file_path, proc_2_udp_dest_ports = proc_2_capture_info

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.