byteblower_test_framework.all module

Convenience module to import everything this package provides.

class byteblower_test_framework.all.BufferAnalyser

Bases: FlowAnalyser

Analyse a video buffer over time.

The analyser provides buffer state, incoming and outgoing data over time. It analyses the initial wait time for the video to start playing out.

This analyser is intended for use with a VideoFlow.

Supports:

Analysis of a single flow

Warning

Does not support aggregation data from multiple flows (via AnalyserAggregator).

__init__(buffer_size: int, play_goal_size: int, max_initial_wait_time: timedelta = datetime.timedelta(seconds=5)) → None

Create the video buffer over time analyser.

Parameters:

buffer_size (int) – Size of the video buffer in Bytes.
play_goal_size (int) –
max_initial_wait_time (timedelta, optional) – Maximum allowed time to wait until the video starts to play, defaults to timedelta(seconds=5)

analyse() → None

Note

Virtual method.

buffer_consume(size: int) → None

buffer_fill(size: int) → None

container_id = 0

details() → Mapping[str, Any] | None

Return the detailed analysis results in pandas-compatible objects.

Can be None if no detailed results are available or applicable.

Note

Virtual method.

Return type:: Mapping[str, Any] | None

property finished: bool: Return whether flow analysis has finished.

Note

Virtual method.

property log: str

Return the summary log text.

Note

Used for textual representation of the results in test reports.

Returns:: Summary log text.
Return type:: str

process() → None

Note

Virtual method.

release() → None

Release all resources used on the ByteBlower system.

render() → str

Return the detailed analysis results in HTML format.

Note

Virtual method.

Return type:: str

property size: int

property size_max: int

updatestats() → None

Note

Virtual method.

class byteblower_test_framework.all.ByteBlowerHtmlReport

Bases: ByteBlowerReport

Generate a report in HTML format.

Generates summary information of test status, test configuration and results from all flows.

This report contains:

A global PASS/FAIL result
Port configuration table
Correlated results
- Aggregated results over all flows (supporting aggregation of over time graphs and summary table)
Per-flow results
- Flow configuration
- Results for all Analysers attached to the flow

__init__(output_dir: str | None = None, filename_prefix: str = 'byteblower', filename: str | None = None, layer2_speed: Layer2Speed | None = Layer2Speed.frame) → None

Create a ByteBlower HTML report generator.

The report is stored under <output_dir>. The default structure of the file name is

<prefix>_<timestamp>.html

where:

<output_dir>: Configurable via output_dir. Defaults to the current working directory.
<prefix>: Configurable via filename_prefix
<timestamp>: Current time. Defined at construction time of the ByteBlowerReport Python object.

Parameters:

output_dir (str, optional) – Override the directory where the report file is stored, defaults to None (meaning that the “current directory” will be used)
filename_prefix (str, optional) – Prefix for the ByteBlower report file name, defaults to ‘byteblower’
filename (str, optional) – Override the complete filename of the report, defaults to None
layer2_speed (Layer2Speed, optional) – Configuration setting to select the layer 2 speed reporting, defaults to frame

add_flow(flow: Flow) → None

Add the flow info.

Parameters:: flow (Flow) – Flow to add the information for

clear() → None

Start with empty report contents.

render(api_version: str, framework_version: str, port_list: DataFrame, scenario_start_timestamp: datetime | None, scenario_end_timestamp: datetime | None) → None

Render the report.

Parameters:: port_list (DataFrame) – Configuration of the ByteBlower Ports.

class byteblower_test_framework.all.ByteBlowerJsonReport

Bases: ByteBlowerReport

Generate report in JSON format.

Generates summary information of test status, test configuration and results from all flows.

This report contains:

Global test status
Port configuration (to-do)
Correlated results
- Aggregated results over all flows (supporting aggregation of over time data (to-do) and summary data)
Per-flow results (to-do)
- Flow configuration
- Results for all Analysers attached to the flow

__init__(output_dir: str | None = None, filename_prefix: str = 'byteblower', filename: str | None = None) → None

Create a ByteBlower JSON report generator.

The report is stored under <output_dir>. The default structure of the file name is

<prefix>_<timestamp>.json

where:

<output_dir>: Configurable via output_dir. Defaults to the current working directory.
<prefix>: Configurable via filename_prefix
<timestamp>: Current time. Defined at construction time of the ByteBlowerReport Python object.

Parameters:

output_dir (str, optional) – Override the directory where the report file is stored, defaults to None (meaning that the “current directory” will be used)
filename_prefix (str, optional) – Prefix for the ByteBlower report file name, defaults to ‘byteblower’
filename (str, optional) – Override the complete filename of the report, defaults to None

add_flow(flow: Flow) → None

Add the flow info.

Parameters:: flow (Flow) – Flow to add the information for

clear() → None

Start with empty report contents.

render(api_version: str, framework_version: str, port_list: DataFrame, scenario_start_timestamp: datetime | None, scenario_end_timestamp: datetime | None) → None

Render the report.

Parameters:: port_list (DataFrame) – Configuration of the ByteBlower Ports.

class byteblower_test_framework.all.ByteBlowerReport

Bases: ABC

Abstract ByteBlower Report interface definition.

__init__(output_dir: str | None = None, filename_prefix: str = 'byteblower', filename: str | None = None) → None

Create a ByteBlower report generator.

The report is stored under <output_dir>. The default structure of the file name is

<prefix>_<timestamp>.<ext>

where:

<output_dir>: Configurable via output_dir. Defaults to the current working directory.
<prefix>: Configurable via filename_prefix
<timestamp>: Current time. Defined at construction time of the ByteBlowerReport Python object.
<ext>: Output type specific file extension.

Parameters:

output_dir (str, optional) – Override the directory where the report file is stored, defaults to None (meaning that the “current directory” will be used)
filename (str, optional) – Override the complete filename of the report, defaults to None
filename_prefix (str, optional) – Prefix for the ByteBlower report file name, defaults to ‘byteblower’

abstract add_flow(flow: Flow) → None

Add the flow info.

Parameters:: flow (Flow) – Flow to add the information for

abstract clear() → None

Start with empty report contents.

abstract render(api_version: str, framework_version: str, port_list: DataFrame, scenario_start_timestamp: datetime | None, scenario_end_timestamp: datetime | None) → None

Render the report.

Parameters:: port_list (DataFrame) – Configuration of the ByteBlower Ports.

property report_url: str

Return the name and location of the generated report.

Returns:: Name and location of the generated report.
Return type:: str

exception byteblower_test_framework.all.ByteBlowerTestFrameworkException

Bases: Exception

Base exception for all ByteBlower Test Framework related exceptions.

class byteblower_test_framework.all.ByteBlowerUnitTestReport

Bases: ByteBlowerReport

Generate test report in Unit XML format.

__init__(output_dir: str | None = None, filename_prefix: str = 'byteblower', filename: str | None = None) → None

Create a ByteBlower Unit test report generator.

The report is stored under <output_dir>. The default structure of the file name is

<prefix>_<timestamp>.xml

where:

<output_dir>: Configurable via output_dir. Defaults to the current working directory.
<prefix>: Configurable via filename_prefix
<timestamp>: Current time. Defined at construction time of the ByteBlowerReport Python object.

Parameters:

output_dir (str, optional) – Override the directory where the report file is stored, defaults to None (meaning that the “current directory” will be used)
filename_prefix (str, optional) – Prefix for the ByteBlower report file name, defaults to ‘byteblower’
filename (str, optional) – Override the complete filename of the report, defaults to None

add_flow(flow: Flow) → None

Add the flow info.

Parameters:: flow (Flow) – Flow to add the information for

clear() → None

Start with empty report contents.

render(api_version: str, framework_version: str, port_list: DataFrame, scenario_start_timestamp: datetime | None, scenario_end_timestamp: datetime | None) → None

Render the report.

Parameters:: port_list (DataFrame) – Configuration of the ByteBlower Ports.

class byteblower_test_framework.all.Endpoint

Bases: Taggable, ABC

ByteBlower Endpoint interface.

Added in version 1.2.0: Added for ByteBlower Endpoint support.

__init__(meeting_point: MeetingPoint, uuid: str, name: str | None = None, tags: Sequence[str] | None = None, **kwargs) → None

Initialize a ByteBlower Endpoint.

Parameters:

meeting_point (MeetingPoint) – Meeting point this Endpoint is registered on
uuid (str) – Unique identifier of the device to use
name (Optional[str], optional) – Friendly name for this endpoint, used for reporting, defaults to None (auto-generated)
tags (Optional[Sequence[str]], optional) – List of tags to assign, defaults to None

Raises:

InvalidInput – when unsupported configuration is provided

property active: bool

Return whether this Endpoint is active.

Returns:: Whether this endpoint is active or not.
Return type:: bool

property bb_endpoint: WirelessEndpoint: Endpoint object from the ByteBlower API.

discover_nat(remote_port: Port, remote_udp_port: int = 49152, local_udp_port: int = 49152) → Tuple[IPv4Address | IPv6Address, int]

Resolve the IP address (and/or UDP port) as seen by remote_port.

This will resolve either the IP address of the endpoint or the public IP address of the (IPv4 NAT/NAPT) gateway when the endpoint is using IPv4 and is located behind a NAT/NAPT gateway.

Note

UDP ports (remote_udp_port and local_udp_port) can be left to the default if you are only interested in the public IP.

Return type:: Tuple[IPv4Address | IPv6Address, int]

property failed: bool: Return whether (IP) address configuration failed.

abstract property gateway: IPv4Address | IPv6Address: Return the default gateway.

Note

Useful for reporting. Furthermore not used in traffic generation or analysis.

Note

Subject to change in dual stack implementations.

abstract property ip: IPv4Address | IPv6Address: Return the preferred IP address.

Note

Subject to change in dual stack implementations.

property meeting_point: MeetingPoint: Meeting Point object from the ByteBlower Test Framework.

property name: str: Return this endpoint’s given friendly name.

abstract property network: IPv4Network | IPv6Network: Return the network of the preferred IP address.

Note

Useful for reporting. Furthermore not used in traffic generation or analysis.

Note

Subject to change in dual stack implementations.

release() → None

Release this endpoint resources used on the ByteBlower system.

Warning

Releasing resources related to traffic generation and analysis should be done first via the Scenario.release() and/or Flow.release().

Note

The ByteBlower Meeting Point is not released. This should be done afterwards via MeetingPoint.release()

property require_nat_discovery: bool

Return whether this endpoint requires NAT/NAPT discovery.

This is typically required when this endpoint is located behind a NAT/NAPT gateway or you are testing on a carrier-grade NAT (CGN/CGNAT, RFC 6888) network.

Note

Hook function for extending Endpoint implementations.

property status: DeviceStatus

Return this endpoint’s current status.

Returns:: The Endpoint’s current status.
Return type:: DeviceStatus

property uuid: WirelessEndpoint: Return unique identifier of the ByteBlower Endpoint app.

property vlan_config: Iterator[Sequence[Tuple[int, int, bool, int]]]

VLAN configurations of the ByteBlower Lower Layer API.

Note

Currently not supported by the ByteBlower Endpoint.

Returns:: Ordered collection (Outer -> Inner) of VLAN configuration tuples
Yield:: VLAN configuration for current layer 2.5
Return type:: Iterator[Sequence[VlanFlatConfig]]

class byteblower_test_framework.all.Frame

Bases: ABC

Frame interface.

__init__(_minimum_length: int, length: int | None = None, udp_src: int | None = None, udp_dest: int | None = None, latency_tag: bool = False) → None

Create the base frame.

Parameters:

_minimum_length (int) – Required minimum length of the frame, used for sanity check
length (Optional[int], optional) – Frame length. This is the layer 2 (Ethernet) frame length excluding Ethernet FCS and excluding VLAN tags, defaults to DEFAULT_FRAME_LENGTH
udp_src (Optional[int], optional) – UDP source port, defaults to UDP_DYNAMIC_PORT_START
udp_dest (Optional[int], optional) – UDP destination port, defaults to UDP_DYNAMIC_PORT_START
latency_tag (bool, optional) – Enable latency tag generation in the Frame, defaults to False

Raises:

InvalidInput – When invalid configuration values are given.

property length: int: Ethernet length without FCS and without VLAN tags.

release(stream: TxStream) → None

Release this frame resources used on the ByteBlower system.

Note

The resources related to the stream itself is not released.

property udp_dest: UDP destination port.

property udp_src: UDP source port.

class byteblower_test_framework.all.FrameBlastingFlow

Bases: Flow

Flow generating and analyzing stateless traffic, mostly UDP.

Create a Frame Blasting flow.

Parameters:

source (Union[Port, Endpoint]) – Sending endpoint of the data stream
destination (Union[Port, Endpoint]) – Receiving endpoint of the data stream
name (str, optional) – Name of this Flow, defaults to auto-generated name when set to None.
bitrate (float, optional) – Rate at which the bits are transmitted (in bit per second). Excludes the VLAN tag bytes (when applicable), mutual exclusive with frame_rate, defaults to None.
frame_rate (float, optional) – Rate at which the frames are transmitted (in frames per second), mutual exclusive with bitrate, defaults to DEFAULT_FRAME_RATE when bitrate is not provided.
number_of_frames (int, optional) – Number of frames to transmit, defaults to DEFAULT_NUMBER_OF_FRAMES
duration (Union[timedelta, float, int], optional) – Duration of the flow in seconds, defaults to None (use number_of_frames instead)
initial_time_to_wait (Union[timedelta, float, int], optional) – Initial time to wait to start the flow. In seconds, defaults to None (start immediately)
frame_list (Sequence[Frame], optional) – List of frames to transmit, mutual exclusive with imix, defaults to None
imix (Imix, optional) – Imix definition of frames to transmit, mutual exclusive with frame_list, defaults to None

Raises:

FeatureNotSupported – When an unsupported source endpoint type is given.
ConflictingInput – When both frame_rate and bitrate are given.
ConflictingInput – When both imix and frame_list are given or when none of both is given.

analyse() → None

Note

Virtual method with implementation. Should be called by child implementations.

property duration: timedelta

Returns the duration of the FrameBlasting flow.

Raises:: InfiniteDuration – If the flow duration is configured to run forever.
Returns:: duration of the flow.
Return type:: timedelta

property finished: bool: Returns True if the flow is done.

property frame_list: Sequence[Frame]

property frame_rate: float

property initial_time_to_wait: timedelta: Return the time to wait before the flow starts.

initialize() → None

Create the stream and add frames.

property number_of_frames: int

prepare_configure() → None

Prepare Frames and perform proper address resolving.

prepare_start(maximum_run_time: timedelta | None = None) → Iterable[SynchronizedExecutable]

Prepare the flow and its analysers to start traffic and analysis.

Warning

No more activities (like address / port discovery, …) allowed in the network under test.

Note

Virtual method with implementation. Should be called by child implementations.

Return type:: Iterable[SynchronizedExecutable]

process() → None

Note

Virtual method with implementation. Should be called by child implementations.

release() → None

Release all resources used on the ByteBlower system.

Releases all resources related to traffic generation and analysis.

Note

Virtual method with implementation. Should be called by child implementations.

Note

The resources related to endpoints and server themselves are not released.

require_stream_data_gatherer() → None

Make sure that the stream data gatherer is available for testing.

Should be called by the FlowAnalyser or the user before starting a test when he needs ByteBlower stream (packet count) data.

property runtime_error_info: Mapping[str, Any]: Returns implementation-specific runtime error info.

stop() → None

Stop all traffic generation and analysis for this flow.

Note

Virtual hook method for child implementations.

Added in version 1.1.0.

property stream_frame_count_data: FrameCountData | None

Get the frame count data from the stream analysis.

Note

Initially created by calling require_stream_data_gatherer()

Returns:: Frame count data
Return type:: FrameCountData

updatestats() → None

Note

Virtual method with implementation. Should be called by child implementations.

wait_until_finished(wait_for_finish: timedelta, result_timeout: timedelta) → None

Wait until the flow finished traffic generation and processing.

Parameters:

wait_for_finish (timedelta) – Time to wait for sessions closing and final packets being received.
result_timeout (timedelta) – Time to wait for Endpoints to finalize and return their results to the Meeting Point.

Added in version 1.2.0: Added for ByteBlower Endpoint support.

class byteblower_test_framework.all.FrameLossAnalyser

Bases: BaseFrameLossAnalyser

Analyse frame count over time.

The analyser also provides the RX and TX frame count and frame loss over the duration of the test.

This analyser is intended for use with a Flow based on a FrameBlastingFlow (for example GamingFlow).

Supports:

Analysis of a single flow
Usage in AnalyserAggregator.

__init__(layer2_speed: Layer2Speed = Layer2Speed.frame, max_loss_percentage: float = 1.0)

Create frame count over time analyser.

Parameters:

layer2_speed (Layer2Speed, optional) – Configuration setting to select the layer 2 speed reporting, defaults to frame
max_loss_percentage (float, optional) – Maximum allowed packet loss in %, defaults to DEFAULT_LOSS_PERCENTAGE

class byteblower_test_framework.all.GamingFlow

Bases: FrameBlastingFlow

Simulate traditional gaming network traffic.

Note

This does not simulate cloud gaming.

__init__(source: Port, destination: Port | Endpoint, name: str | None = None, packet_length: int = 110, packet_length_deviation: float = 20, packet_length_min: int = 22, packet_length_max: int = 1480, frame_rate: float = 30, imix_number_of_frames: int = 20, udp_src: int | None = None, udp_dest: int | None = None, ip_dscp: int | None = None, ip_ecn: int | None = None, ip_traffic_class: int | None = None, max_threshold_latency: float = 1.0, **kwargs) → None

Instantiate a new Gaming Flow.

Parameters:

source (Port) – Source port for this flow
destination (Union[Port, Endpoint]) – Destination Port for this flow
name (str, optional) – Name for this Flow, defaults to None
packet_length (int, optional) – Mean UDP length of the frames we are going to send, defaults to 110
packet_length_deviation (float, optional) – Deviation of the frame length, defaults to 20
packet_length_min (int, optional) – Minimum UDP packet length, defaults to 22
packet_length_max (int, optional) – Maximum UDP packet length, defaults to 1480
frame_rate (float, optional) – Packet rate at which we will send these frames, defaults to 30
imix_number_of_frames (int, optional) – Add <x> frames with a length which is normally distributed, defaults to 20
udp_src (Optional[int], optional) – UDP src port, defaults to UDP_DYNAMIC_PORT_START
udp_dest (Optional[int], optional) – UDP dest port, defaults to UDP_DYNAMIC_PORT_START
ip_dscp (Optional[int], optional) – IP Differentiated Services Code Point (DSCP), mutual exclusive with ip_traffic_class, defaults to DEFAULT_IP_DSCP
ip_ecn (Optional[int], optional) – IP Explicit Congestion Notification (ECN), mutual exclusive with ip_traffic_class, defaults to DEFAULT_IP_ECN
ip_traffic_class (int | None) – The IP traffic class value is used to specify the exact value of either the IPv4 ToS field or the IPv6 Traffic Class field, mutual exclusive with ip_dscp and ip_ecn, defaults to field value composed from ip_dscp and ip_ecn.
max_threshold_latency (float, optional) – Threshold in ms. Is percentile 99 of the this flow is below this threshold, the flow will pass for this test, defaults to 1.0

Raises:

ValueError – When an unsupported source Port type is given.
FeatureNotSupported – When the source is a ByteBlower Endpoint.

analyse() → None

Pass or fail for this test.

class byteblower_test_framework.all.HTTPFlow

Bases: TcpFlow

Flow for generating and analyzing TCP and HTTP data traffic.

HTTP flow involves a client initiating a TCP connection to a server, exchanging HTTP requests and responses (GET/PUT), and then closing the connection. This enables the transfer of web content between client and server.

Since v2.22.0, ByteBlower supports L4S for HTTP flow. Low Latency, Low Loss, and Scalable Throughput (L4S) is a versatile technology enhancing internet performance across various networks like fibre, 5G, and Wi-Fi networks. It innovates on traditional TCP by using the Prague requirements, to more effectively signal and respond to congestion through Explicit Congestion Notification (ECN). This approach allows for quicker, more precise adjustments in data transmission, leading to increased network efficiency and reduced latency. More details on L4S and low latency testing can be found in Test Case: Low Latency.

Changed in version 1.3.0: Support for L4S was added

Create an HTTP flow.

Parameters:

source (Union[Port, Endpoint]) – Sending endpoint of the data traffic
destination (Union[Port, Endpoint]) – Receiving endpoint of the data traffic
name (Optional[str], optional) – Name of this Flow, defaults to auto-generated name when set to None.
http_method (HttpMethod, optional) – HTTP Method of this request, defaults to HttpMethod.AUTO
tcp_server_port (Optional[int], optional) – TCP port of the HTTP server, defaults to None
tcp_client_port (Optional[int], optional) – TCP port of the HTTP client, defaults to None
request_duration (Optional[Union[timedelta, float, int]], optional) – Duration of the HTTP data transfer. Mutual exclusive with request_size, defaults to None
request_size (Optional[int], optional) – Size of the HTTP data to transfer (in Bytes). Mutual exclusive with request_duration, defaults to None
initial_time_to_wait (Optional[Union[timedelta, float, int]], optional) – Initial time to wait to start the flow, defaults to None
rate_limit (Optional[int], optional) –
Limit the data traffic rate (in Bytes per second). Mutual exclusive with maximum_bitrate, defaults to None (== no limit)

Deprecated since version 1.2.0: Deprecated rate_limit in favor of maximum_bitrate. Will be removed in the next release.
maximum_bitrate (Optional[Union[int, float]], optional) –
Limit the data traffic rate (in bits per second). Mutual exclusive with rate_limit, defaults to None (== no limit)

Added in version 1.2.0: Added maximum_bitrate deprecating rate_limit.
enable_tcp_prague (Optional[bool], optional) –
When given, enable TCP Prague congestion avoidance algorithm on both TCP client and server, defaults to None. (Server default; default for ByteBlower Port, host operating system default for ByteBlower Endpoint).
Note
- L4S support requires at least ByteBlower API v2.22.0, Server and Meeting Point v2.22.0, and ByteBlower Endpoint v2.22.0
- When using Endpoints, L4S must be supported and enabled in the hosting OS
Added in version 1.3.0: Added enable_tcp_prague for L4S support in HTTP flow.
receive_window_scaling (Optional[int], optional) –
When given, enable receive window scaling with the given scale factor, defaults to None.

When ByteBlower Endpoints are involved, this setting will not be applied on them, but only on the HTTP Server on the ByteBlower Port. The ByteBlower Endpoint has no control over the TCP parameters of the host operating system’s. It is then up to the Endpoint’s host configuration whether this setting will be applicable or not.
slow_start_threshold (Optional[int], optional) –
Slow start threshold value of TCP, defaults to None.

When ByteBlower Endpoints are involved, this setting will not be applied on them, but only on the HTTP Server on the ByteBlower Port. The ByteBlower Endpoint has no control over the TCP parameters of the host operating system’s. It is then up to the Endpoint’s host configuration whether this setting will be applicable or not.
ip_dscp (Optional[int], optional) – IP Differentiated Services Code Point (DSCP), mutual exclusive with ip_traffic_class, defaults to DEFAULT_IP_DSCP
ip_ecn (Optional[int], optional) – IP Explicit Congestion Notification (ECN), mutual exclusive with ip_traffic_class, defaults to DEFAULT_IP_ECN
ip_traffic_class (Optional[int], optional) – The IP traffic class value is used to specify the exact value of either the IPv4 ToS field or the IPv6 Traffic Class field, mutual exclusive with ip_dscp and ip_ecn, defaults to field value composed from ip_dscp and ip_ecn.

Raises:

ConflictingInput – When invalid combination of configuration parameters is given

property duration: timedelta

Returns the duration of the HTTP flow.

Raises:: NotDurationBased – If the HTTPFlow is sized based.
Returns:: duration of the flow.
Return type:: timedelta

property enable_tcp_prague: bool | None: Whether TCP Prague is enabled.

Added in version 1.3.0: Add enabling TCP Prague for L4S

property initial_time_to_wait: timedelta: Return the time to wait before the flow starts.

property maximum_bitrate: int | float | None

Return the requested HTTP rate limit.

Returns:: The maximum bitrate, in bits per second.
Return type:: Optional[int]

prepare_start(maximum_run_time: timedelta | None = None) → Iterable[SynchronizedExecutable]

Start a HTTP server and schedule the client data transfer.

Return type:: Iterable[SynchronizedExecutable]

property rate_limit: float | None

Return the requested HTTP rate limit.

Returns:: The rate limit, in bytes per second.
Return type:: Optional[float]

property receive_window_scaling: int | None: TCP Receive Window scaling.

release() → None

Release all resources used on the ByteBlower system.

Releases all resources related to traffic generation and analysis.

Note

Virtual method with implementation. Should be called by child implementations.

Note

The resources related to endpoints and server themselves are not released.

property slow_start_threshold: int | None: TCP Slow Start Threshold.

property tcp_server_port: int | None: TCP port of the HTTP server.

class byteblower_test_framework.all.HttpAnalyser

Bases: FlowAnalyser

Analyse HTTP and TCP statistics over time.

The analyser currently only provides the HTTP goodput over time and the average HTTP goodput over the duration of the test.

Note

There is no specific analysis performed and the test will always state no analysis is done.

This analyser is intended for use with a HTTPFlow.

Supports:

Analysis of a single flow

Warning

Does not support aggregation data from multiple flows (via AnalyserAggregator).

__init__(analyser_type: str = 'HTTP analyser', http_data_class=<class 'byteblower_test_framework._analysis.storage.tcp.HttpData'>)

Create the HTTP and TCP statistics over time analyser.

analyse() → None

Note

Virtual method.

details() → Mapping[str, Any] | None

Return the detailed analysis results in pandas-compatible objects.

Can be None if no detailed results are available or applicable.

Note

Virtual method.

Return type:: Mapping[str, Any] | None

property finished: bool: Return whether flow analysis has finished.

Note

Virtual method.

property flow: TcpFlow

Return Flow implementation.

Useful for correct type hinting.

property http_method: Return the configured HTTP Request Method.

initialize() → None

Configure the flow analyser.

Warning

No more activities (like address / port discovery, …) allowed in the network under test.

Note

Virtual method.

property log: str

Return the summary log text.

Note

Used for textual representation of the results in test reports.

Returns:: Summary log text.
Return type:: str

prepare_configure() → None

Prepare the flow analyser to be configured.

At this point, it is allowed to perform address resolution, port discovery, …

Note

Virtual method.

prepare_start(maximum_run_time: timedelta | None = None) → None

Prepare the flow analyser to start analysis.

Warning

No more activities (like address / port discovery, …) allowed in the network under test.

Note

Virtual method.

Parameters:: maximum_run_time (Optional[timedelta], optional) – Maximum run time of the scenario

process() → None

Note

Virtual method.

release() → None

Release all resources used on the ByteBlower system.

render() → str

Return the detailed analysis results in HTML format.

Note

Virtual method.

Return type:: str

property rx_first_client: Timestamp | None: Time when the first packet was received at the HTTP Client.

property rx_first_server: Timestamp | None: Time when the first packet was received at the HTTP Server.

property rx_last_client: Timestamp | None: Time when the last packet was received at the HTTP Client.

property rx_last_server: Timestamp | None: Time when the last packet was received at the HTTP Server.

property total_rx_client: int: Number of received bytes at HTTP Client.

property total_rx_server: int: Number of received bytes at HTTP Server.

property total_tx_client: int: Number of transmitted bytes at HTTP Client.

property total_tx_server: int: Number of transmitted bytes at HTTP Server.

property tx_first_client: Timestamp | None: Time when the first packet was transmitted at the HTTP Client.

property tx_first_server: Timestamp | None: Time when the first packet was transmitted at the HTTP Server.

property tx_last_client: Timestamp | None: Time when the last packet was transmitted at the HTTP Client.

property tx_last_server: Timestamp | None: Time when the last packet was transmitted at the HTTP Server.

updatestats() → None

Analyse the result.

What would be bad?

TCP sessions not going to Finished

class byteblower_test_framework.all.HttpMethod

Bases: Enum

HTTP method used for HTTP (client) sessions.

AUTO = 'Automatic'

GET = 'GET'

PUT = 'PUT'

class byteblower_test_framework.all.IPv4Endpoint

Bases: NatDiscoveryEndpoint

ByteBlower Endpoint interface.

This type of endpoint supports discovery of the actual source IP address (and UDP port) used by an Endpoint when transmitting to a specific destination. This is particularly important for IPv4 multihoming.

The discovery also supports Traditional NAT (RFC 3022, Traditional IP Network Address Translator). Traditional NAT has two variants: Basic NAT and Network Address Port Translation (NAPT).

Added in version 1.2.0: Added for ByteBlower Endpoint support.

__init__(meeting_point: MeetingPoint, uuid: str, name: str | None = None, **kwargs) → None

Initialize a ByteBlower IPv4 Endpoint.

Parameters:

meeting_point (MeetingPoint) – Meeting point this Endpoint is registered on
uuid (str) – Unique identifier of the device to use
name (Optional[str], optional) – Friendly name for this endpoint, used for reporting, defaults to None (auto-generated)
tags (Optional[Sequence[str]], optional) – List of tags to assign, defaults to None

Raises:

InvalidInput – when unsupported configuration is provided

property gateway: IPv4Address: Return the default gateway.

Note

Useful for reporting. Furthermore not used in traffic generation or analysis.

property ip: IPv4Address: Return the Endpoint host IP address.

property network: IPv4Network: Return the network of the preferred IP address.

Note

Useful for reporting. Furthermore not used in traffic generation or analysis.

class byteblower_test_framework.all.IPv4Frame

Bases: Frame

Frame interface for IPv4.

Create the interface to an IPv4 frame.

Parameters:

length (Optional[int], optional) – Frame length. This is the layer 2 (Ethernet) frame length excluding Ethernet FCS and excluding VLAN tags, defaults to DEFAULT_FRAME_LENGTH
udp_src (Optional[int], optional) – UDP source port, defaults to UDP_DYNAMIC_PORT_START
udp_dest (Optional[int], optional) – UDP destination port, defaults to UDP_DYNAMIC_PORT_START
ip_dscp (Optional[int], optional) – IP Differentiated Services Code Point (DSCP), mutual exclusive with ipv4_tos, defaults to DEFAULT_IP_DSCP
ip_ecn (Optional[int], optional) – IP Explicit Congestion Notification (ECN), mutual exclusive with ipv4_tos, defaults to DEFAULT_IP_ECN
ipv4_tos (Optional[int], optional) – Exact IPv4 ToS field value, mutual exclusive with ip_dscp and ip_ecn, defaults to field value composed from ip_dscp and ip_ecn.
latency_tag (bool, optional) – Enable latency tag generation in the Frame, defaults to False

Raises:

InvalidInput – When invalid configuration values are given.
ConflictingInput – When invalid combination of configuration parameters is given

class byteblower_test_framework.all.IPv4Port

Bases: Port

ByteBlower Port interface for IPv4.

Initialize a ByteBlowerPort.

Note

L2 is only configured if:

Explicitly given MAC address
Layer 3 is configured

A port without L2/L3 configuration can for example be used for pure ‘promiscuous’ capturing of data.

Note

Configuring VLAN Protocol ID (TPID) requires at least ByteBlower server version >= 2.20

property failed: bool: Return whether (IP) address configuration failed.

property gateway: IPv4Address: Return the default gateway.

Note

Subject to change in dual stack implementations.

property ip: IPv4Address: Return the preferred IP address.

Note

Subject to change in dual stack implementations.

property layer3: IPv4Configuration: IPv4 configuration of the ByteBlower Lower Layer API.

Note

Subject to change in dual stack implementations.

property network: IPv4Network: Return the network of the preferred IP address.

Note

Subject to change in dual stack implementations.

class byteblower_test_framework.all.IPv6Endpoint

Bases: NatDiscoveryEndpoint

ByteBlower Endpoint interface for IPv6.

This type of endpoint supports discovery of the actual source IP address (and UDP port) used by an Endpoint when transmitting to a specific destination.

This is particularly important for IPv6 multihoming (RFC 7157, IPv6 Multihoming without Network Address Translation).

The discovery can also support NPTv6 (RFC 6296, IPv6-to-IPv6 Network Prefix Translation).

Added in version 1.2.0: Added for ByteBlower Endpoint support.

__init__(meeting_point: MeetingPoint, uuid: str, name: str | None = None, network_interface: str | None = None, **kwargs) → None

Initialize ByteBlower IPv6 Endpoint.

Parameters:

meeting_point (MeetingPoint) – Meeting point this Endpoint is registered on
uuid (str) – Unique identifier of the device to use
name (Optional[str], optional) – Friendly name for this endpoint, used for reporting, defaults to None (auto-generated)
network_interface (Optional[str]) –
Name of the network interface used by the endpoint for traffic generation and analysis, defaults to None (first interface found with IPv6 address).

Note

Mostly relevant for reporting and frame blasting flows. When multiple network interfaces are available on the Endpoint and automatic selection is not (always) correct.
tags (Optional[Sequence[str]], optional) – List of tags to assign, defaults to None

Raises:

InvalidInput – when unsupported configuration is provided

property gateway: IPv6Address: Return the default gateway.

Note

Useful for reporting. Furthermore not used in traffic generation or analysis.

property ip: IPv6Address: Return the Endpoint host IP address.

property network: IPv6Network: Return the network of the preferred IP address.

Note

Useful for reporting. Furthermore not used in traffic generation or analysis.

class byteblower_test_framework.all.IPv6Frame

Bases: Frame

Frame interface for IPv6.

Create the interface to an IPv6 frame.

Parameters:

length (Optional[int], optional) – Frame length. This is the layer 2 (Ethernet) frame length excluding Ethernet FCS and excluding VLAN tags, defaults to DEFAULT_FRAME_LENGTH
udp_src (Optional[int], optional) – UDP source port, defaults to UDP_DYNAMIC_PORT_START
udp_dest (Optional[int], optional) – UDP destination port, defaults to UDP_DYNAMIC_PORT_START
ip_dscp (Optional[int], optional) – IP Differentiated Services Code Point (DSCP), mutual exclusive with ipv6_tc, defaults to DEFAULT_IP_DSCP
ip_ecn (Optional[int], optional) – IP Explicit Congestion Notification (ECN), mutual exclusive with ipv6_tc, defaults to DEFAULT_IP_ECN
ipv6_tc (Optional[int], optional) – Exact IPv6 Traffic Class field, mutual exclusive with ip_dscp and ip_ecn, defaults to field value composed from ip_dscp and ip_ecn.
latency_tag (bool, optional) – Enable latency tag generation in the Frame, defaults to False

Raises:

InvalidInput – When invalid configuration values are given.
ConflictingInput – When invalid combination of configuration parameters is given

class byteblower_test_framework.all.IPv6Port

Bases: Port

ByteBlower Port interface for IPv6.

Initialize a ByteBlowerPort.

Note

L2 is only configured if:

Explicitly given MAC address
Layer 3 is configured

A port without L2/L3 configuration can for example be used for pure ‘promiscuous’ capturing of data.

Note

Configuring VLAN Protocol ID (TPID) requires at least ByteBlower server version >= 2.20

property failed: bool: Return whether (IP) address configuration failed.

property gateway: IPv6Address: Return the default gateway.

Note

Subject to change in dual stack implementations.

property ip: IPv6Address: Return the preferred IP address.

Note

Subject to change in dual stack implementations.

property layer3: IPv6Configuration: IPv6 configuration of the ByteBlower Lower Layer API.

Note

Subject to change in dual stack implementations.

property network: IPv6Network: Return the network of the preferred IP address.

Note

Subject to change in dual stack implementations.

class byteblower_test_framework.all.Imix

Bases: object

Configuration of an Internet mix.

For a given UDP source and destination port, define a weighted collection of frame sizes.

Note

We tend to use a single UDP port for all frames. This has some benefits in initialization time (for example much less need for NAT/NAPT resolution).

__init__(frame_config: Sequence[ImixFrameConfig] = [ImixFrameConfig(length=72, weight=34), ImixFrameConfig(length=124, weight=6), ImixFrameConfig(length=252, weight=4), ImixFrameConfig(length=508, weight=4), ImixFrameConfig(length=1020, weight=9), ImixFrameConfig(length=1276, weight=25), ImixFrameConfig(length=1510, weight=18)], udp_src: int = 49152, udp_dest: int = 49152, ip_dscp: int | None = None, ip_ecn: int | None = None, ip_traffic_class: int | None = None, latency_tag: bool = False, random_order: bool = True) → None

Create a frame based on the (source) Port type.

Parameters:

frame_config (Sequence[ImixFrameConfig], optional) – Collection of IMIX frame configurations, defaults to DEFAULT_IMIX_FRAME_CONFIG
udp_src (int, optional) – UDP source port, defaults to UDP_DYNAMIC_PORT_START
udp_dest (int, optional) – UDP destination port, defaults to UDP_DYNAMIC_PORT_START
ip_dscp (Optional[int], optional) – IP Differentiated Services Code Point (DSCP), mutual exclusive with ip_traffic_class, defaults to DEFAULT_IP_DSCP
ip_ecn (Optional[int], optional) – IP Explicit Congestion Notification (ECN), mutual exclusive with ip_traffic_class, defaults to DEFAULT_IP_ECN
ip_traffic_class (int | None) – The IP traffic class value is used to specify the exact value of either the IPv4 ToS field or the IPv6 Traffic Class field, mutual exclusive with ip_dscp and ip_ecn, defaults to field value composed from ip_dscp and ip_ecn.
latency_tag (bool, optional) – Enable latency tag generation in the Frame, defaults to False
random_order (bool, optional) – Enable shuffle of the generated frames, defaults to True

Raises:

InvalidInput – When invalid configuration values are given.
ConflictingInput – When invalid combination of configuration parameters is given

property udp_dest: int: UDP destination port.

property udp_src: int: UDP source port.

class byteblower_test_framework.all.ImixFrameConfig

Bases: object

Configuration for an IMIX frame.

__init__(length: int, weight: int) → None

length: int: Frame length. This is the layer 2 (Ethernet) frame length excluding Ethernet FCS and excluding VLAN tags.

weight: int: Weight of this frame size in the list of frames in the Imix.

exception byteblower_test_framework.all.InfiniteDuration

Bases: ByteBlowerTestFrameworkException

Raised when a flow duration is not specified.

class byteblower_test_framework.all.L4SHttpAnalyser

Bases: HttpAnalyser

Analyse L4S enabled HTTP and TCP statistics over time.

Over the duration of the test, this analyser provides:

HTTP goodput over time
HTTP retransmissions
Average Round Trip Time (RTT)
Min/Max RTT
Congestion Experienced (CE) count

Note

There is no specific analysis performed and the test will always state no analysis is done.

This analyser is used with a HTTPFlow, where TCP Prague is enabled.

Supports:

Analysis of a single flow

Warning

Does not support aggregation data from multiple flows (via AnalyserAggregator).

Note

L4S support requires at least ByteBlower API v2.22.0, Server and Meeting Point v2.22.0, and ByteBlower Endpoint v2.22.0
When using Endpoints, L4S must be supported and enabled in the hosting OS

Added in version 1.3.0: Added L4S enabled HTTP and its analysers.

__init__(): Create the L4S and RTT statistics for HTTP and TCP over time analyser.

class byteblower_test_framework.all.LatencyCDFFrameLossAnalyser

Bases: BaseLatencyCDFFrameLossAnalyser

Analyse latency CDF and total frame count.

The analyser provides the latency CDF graph, RX and TX frame count and byte loss over the duration of the test. For the latency results you will also have the average, minimum and maximum latency and average latency jitter.

This analyser is intended for use with a Flow based on a FrameBlastingFlow (for example GamingFlow).

Supports:

Analysis of a single flow
Summary results for multiple flows (via AnalyserAggregator)

Warning

Does not provide over time results for AnalyserAggregator.

__init__(layer2_speed: Layer2Speed = Layer2Speed.frame, max_loss_percentage: float = 1.0, max_threshold_latency: float = 5, quantile: float = 99.9)

Create the latency CDF and total frame count analyser.

The latency for the CDF graph will be analysed over a range of [0, 50 * max_threshold_latency[.

Parameters:

layer2_speed (Layer2Speed, optional) – Configuration setting to select the layer 2 speed reporting, defaults to frame
max_loss_percentage (float, optional) – Maximum allowed byte loss in %, defaults to DEFAULT_LOSS_PERCENTAGE
max_threshold_latency (float, optional) – Maximum allowed average latency in milliseconds, defaults to DEFAULT_MAX_LATENCY_THRESHOLD
quantile (float, optional) – Quantile for which the latency must be less than the given maximum average latency, defaults to DEFAULT_QUANTILE

class byteblower_test_framework.all.LatencyFrameLossAnalyser

Bases: BaseLatencyFrameLossAnalyser

Analyse latency and frame count over time.

The analyser also provides the RX and TX frame count and byte loss over the duration of the test. For the latency results you will also have the average, minimum and maximum latency and average latency jitter.

This analyser is intended for use with a Flow based on a FrameBlastingFlow (for example GamingFlow).

Supports:

Analysis of a single flow
Usage in AnalyserAggregator.

__init__(layer2_speed: Layer2Speed = Layer2Speed.frame, max_loss_percentage: float = 1.0, max_threshold_latency: float = 5)

Create the latency and frame count over time analyser.

Parameters:

layer2_speed (Layer2Speed, optional) – Configuration setting to select the layer 2 speed reporting, defaults to frame
max_loss_percentage (float, optional) – Maximum allowed byte loss in %, defaults to DEFAULT_LOSS_PERCENTAGE
max_threshold_latency (float, optional) – Maximum allowed average latency in milliseconds, defaults to DEFAULT_MAX_LATENCY_THRESHOLD

class byteblower_test_framework.all.Layer2Speed

Bases: Enum

What will be included in the Layer 2 speed calculation.

frame = 'frame'

Frame without FCS.

Frame (as build and send by ByteBlower)

This way, each Frame gets 0 Bytes extra.

frame_with_fcs = 'frame_with_fcs'

Frame with FCS.

Frame (as build and send by ByteBlower)
FCS (CRC Frame Checksum, 4 Bytes)

This way, each Frame gets 4 Bytes extra.

physical = 'physical'

Frame with FCS and physical overhead.

Frame (as build and send by ByteBlower)
FCS (CRC Frame Checksum, 4 Bytes)
Preamble (7 Bytes)
SFD (Start Frame Delimiter, 1 Byte)
Pause (12 Bytes)

This way, each Frame gets 24 Bytes extra.

class byteblower_test_framework.all.MeetingPoint

Bases: object

ByteBlower Meeting Point interface.

Added in version 1.2.0: Added for ByteBlower Endpoint support.

__init__(ip_or_host: str) → None

Connect to the ByteBlower Meeting Point.

Parameters:: ip_or_host (str) – The connection address. This can be the hostname or IPv4/IPv6 address of the ByteBlower Meeting Point.

static __new__(cls, ip_or_host: str)

property bb_meeting_point: MeetingPoint: Object from the ByteBlower API.

property info: str: Return connection address this Meeting Point.

release() → None

Release this host related resources used on the ByteBlower system.

Warning

Releasing resources related to traffic generation and analysis should be done first via the Scenario.release() and/or Flow.release().

Warning

Releasing endpoint resources should be done first via Port.release().

release_endpoint(endpoint: WirelessEndpoint) → None

Release this endpoint resources used on the ByteBlower system.

Removes this device from the list of endpoints used in the test and destroys it on the Meeting Point.

Parameters:: endpoint (LLEndpoint) – Endpoint to release

reserve_endpoint(uuid: str) → WirelessEndpoint

Add device to the list of endpoints used in the test.

Return type:: WirelessEndpoint

property timestamp: datetime: Return the current time on the Meeting Point.

class byteblower_test_framework.all.MobileFrame

Bases: ABC

Mobile Frame Interface.

Added in version 1.2.0: Added for ByteBlower Endpoint support.

Create the mobile frame for the wireless endpoint.

Parameters:

length (int, optional) – Frame length. This is the layer 2 (Ethernet) frame length excluding Ethernet FCS and excluding VLAN tags, defaults to DEFAULT_FRAME_LENGTH
udp_src (int, optional) – UDP source port, defaults to UDP_DYNAMIC_PORT_START
udp_dest (int, optional) – UDP destination port, defaults to UDP_DYNAMIC_PORT_START
ip_dscp (Optional[int], optional) – IP Differentiated Services Code Point (DSCP), mutual exclusive with ip_traffic_class, defaults to DEFAULT_IP_DSCP
ip_ecn (Optional[int], optional) – IP Explicit Congestion Notification (ECN), mutual exclusive with ip_traffic_class, defaults to DEFAULT_IP_ECN
ip_traffic_class (Optional[int], optional) – The IP traffic class value is used to specify the exact value of either the IPv4 ToS field or the IPv6 Traffic Class field, mutual exclusive with ip_dscp and ip_ecn, defaults to field value composed from ip_dscp and ip_ecn.
latency_tag (bool, optional) – Enable latency tag generation in the Frame, defaults to False

Raises:

InvalidInput – When invalid configuration values are given.
ConflictingInput – When invalid combination of configuration parameters is given

property length: int: Ethernet length without FCS and without VLAN tags.

release(stream: StreamMobile) → None

Release this frame resources used on the ByteBlower system.

Note

The resources related to the stream itself is not released.

property udp_dest: UDP destination port.

property udp_src: UDP source port.

class byteblower_test_framework.all.NatDiscoveryEndpoint

Bases: Endpoint

ByteBlower Endpoint interface requiring NAT/NAPT discovery.

This type of endpoint supports discovery of the actual source IP address (and UDP port) used by an Endpoint when transmitting to a specific destination.

This is particularly important for IPv4 multihoming or IPv6 multihoming (RFC 7157, IPv6 Multihoming without Network Address Translation).

For IPv4, the discovery also supports Traditional NAT (RFC 3022, Traditional IP Network Address Translator). Traditional NAT has two variants: Basic NAT and Network Address Port Translation (NAPT).

For IPv6, the discovery can also support NPTv6 (RFC 6296, IPv6-to-IPv6 Network Prefix Translation).

Added in version 1.2.0: Added for ByteBlower Endpoint support.

__init__(meeting_point: MeetingPoint, uuid: str, name: str | None = None, **kwargs) → None

Initialize a ByteBlower Endpoint.

Parameters:

meeting_point (MeetingPoint) – Meeting point this Endpoint is registered on
uuid (str) – Unique identifier of the device to use
name (Optional[str], optional) – Friendly name for this endpoint, used for reporting, defaults to None (auto-generated)
tags (Optional[Sequence[str]], optional) – List of tags to assign, defaults to None

Raises:

InvalidInput – when unsupported configuration is provided

discover_nat(remote_port: Port, remote_udp_port: int = 49152, local_udp_port: int = 49152) → Tuple[IPv4Address | IPv6Address, int]

Resolve the IP address (and/or UDP port) as seen by remote_port.

This will resolve either the IP address of the endpoint or the public IP address of the (IPv4 NAT/NAPT) gateway when the endpoint is using IPv4 and is located behind a NAT/NAPT gateway.

Note

UDP ports (remote_udp_port and local_udp_port) can be left to the default if you are only interested in the public IP.

Return type:: Tuple[IPv4Address | IPv6Address, int]

property public_ip: IPv4Address | IPv6Address: Return the public IP address resolved from last NAT discovery.

property require_nat_discovery: bool

Return whether this endpoint requires NAT/NAPT discovery.

This is typically required when this endpoint is located behind a NAT/NAPT gateway or you are testing on a carrier-grade NAT (CGN/CGNAT, RFC 6888) network.

class byteblower_test_framework.all.NatDiscoveryIPv4Port

Bases: IPv4Port

ByteBlower Port interface for IPv4 which requires NAT/NAPT discovery.

This type of endpoint supports discovery of Traditional NAT (RFC 3022, Traditional IP Network Address Translator). Traditional NAT has two variants: Basic NAT and Network Address Port Translation (NAPT).

Changed in version 1.2.0: Improved naming for NAT/NAPT discovery related interfaces.

Initialize a ByteBlowerPort.

Note

L2 is only configured if:

Explicitly given MAC address
Layer 3 is configured

A port without L2/L3 configuration can for example be used for pure ‘promiscuous’ capturing of data.

Note

Configuring VLAN Protocol ID (TPID) requires at least ByteBlower server version >= 2.20

discover_nat(remote_port: IPv4Port, remote_udp_port: int = 49152, local_udp_port: int = 49152) → Tuple[IPv4Address, int]

Resolve the IP address (and/or UDP port) as seen by remote_port.

This will resolve either the IP address of the endpoint or the public IP address of the (IPv4 NAT/NAPT) gateway when the endpoint is using IPv4 and is located behind a NAT/NAPT gateway.

Note

UDP ports (remote_udp_port and local_udp_port) can be left to the default if you are only interested in the public IP.

Return type:: Tuple[IPv4Address, int]

property public_ip: IPv4Address: Return the public IP address resolved from last NAT discovery.

property require_nat_discovery: bool

Return whether this endpoint requires NAT/NAPT discovery.

This is typically required when this endpoint is located behind a NAT/NAPT gateway or you are testing on a carrier-grade NAT (CGN/CGNAT, RFC 6888) network.

Note

Hook function for extending Port implementations.

Changed in version 1.2.0: Improved naming for NAT/NAPT discovery related interfaces.

exception byteblower_test_framework.all.NotDurationBased

Bases: ByteBlowerTestFrameworkException

Raised when a flow is not duration based.

class byteblower_test_framework.all.Port

Bases: Taggable, ABC

ByteBlower Port interface.

Initialize a ByteBlowerPort.

Note

L2 is only configured if:

Explicitly given MAC address
Layer 3 is configured

A port without L2/L3 configuration can for example be used for pure ‘promiscuous’ capturing of data.

Note

Configuring VLAN Protocol ID (TPID) requires at least ByteBlower server version >= 2.20

property bb_port: ByteBlowerPort

discover_nat(remote_port: Port, remote_udp_port: int = 49152, local_udp_port: int = 49152) → Tuple[IPv4Address | IPv6Address, int]

Resolve the IP address (and/or UDP port) as seen by remote_port.

This will resolve either the IP address of the endpoint or the public IP address of the (IPv4 NAT/NAPT) gateway when the endpoint is using IPv4 and is located behind a NAT/NAPT gateway.

Note

UDP ports (remote_udp_port and local_udp_port) can be left to the default if you are only interested in the public IP.

Changed in version 1.2.0: Make endpoint interfaces consistent. Generic interface which will return the own IP address and local UDP port when no address/port discovery is required.

Return type:: Tuple[IPv4Address | IPv6Address, int]

abstract property failed: bool: Return whether (IP) address configuration failed.

abstract property gateway: IPv4Address | IPv6Address: Return the default gateway.

Note

Subject to change in dual stack implementations.

abstract property ip: IPv4Address | IPv6Address: Return the preferred IP address.

Note

Subject to change in dual stack implementations.

property layer2_5: Sequence[Layer25Configuration]

Layer 2.5 configurations of the ByteBlower Lower Layer API.

Returns:: Ordered collection of Layer 2.5 Configuration objects
Return type:: Sequence[Layer25Configuration]

property layer3: Layer3Configuration: Layer 3 configuration of the ByteBlower Lower Layer API.

Note

Subject to change in dual stack implementations.

property mac: str: Return the MAC address currently configured on this endpoint.

property name: str: Return this endpoint’s given friendly name.

abstract property network: IPv4Network | IPv6Network: Return the network of the preferred IP address.

Note

Subject to change in dual stack implementations.

property port_type: str

release() → None

Release this endpoint resources used on the ByteBlower system.

Warning

Releasing resources related to traffic generation and analysis should be done first via the Scenario.release() and/or Flow.release().

Note

The ByteBlower Server is not released. This should be done afterwards via Server.release()

property require_nat_discovery: bool

Return whether this endpoint requires NAT/NAPT discovery.

This is typically required when this endpoint is located behind a NAT/NAPT gateway or you are testing on a carrier-grade NAT (CGN/CGNAT, RFC 6888) network.

Note

Hook function for extending Port implementations.

Changed in version 1.2.0: Improved naming for NAT/NAPT discovery related interfaces.

property server: Server

property vlan_config: Iterator[Sequence[Tuple[int, int, bool, int]]]

VLAN configurations of the ByteBlower Lower Layer API.

Returns:: Ordered collection (Outer -> Inner) of VLAN configuration tuples
Yield:: VLAN configuration for current layer 2.5
Return type:: Iterator[Sequence[VlanFlatConfig]]

class byteblower_test_framework.all.Scenario

Bases: object

ByteBlower Test Scenario interface.

Changed in version 1.2.0: The scenario runtime has been improved with addition of ByteBlower Endpoint support.

__init__() → None

Make a base test scenario.

add_flow(flow: Flow) → None

add_report(report: ByteBlowerReport) → None

property duration: datetime | None

Return the actual duration of the last Scenario run.

The duration is calculated as start_timestamp() - end_timestamp().

Returns:: Actual duration of the last run.
Return type:: Optional[datetime]

property end_timestamp: datetime | None

Return the timestamp when the Scenario was finished.

The end timestamp is the timestamp right after stopping the flows and analysing the final results. This is logged at the end of the Scenario.run() call.

Note

The time between flow analysis and flow and endpoint cleanup is not taken into account here.

Returns:: End time of the last run
Return type:: Optional[datetime]

property flows: Sequence[Flow]

Returns the list of flows added to this Scenario.

Returns:: List of added flows.
Return type:: List[Flow]

release() → None

Release all resources used on the ByteBlower system.

Releases all resources related to traffic generation and analysis.

Note

The ByteBlower Ports / Endpoints themselves are not released.

report() → None

run(maximum_run_time: timedelta | None = None, wait_for_finish: timedelta | None = None, duration: timedelta | None = None) → None

Run the scenario.

if max_run_time is specified, the scenario will limit the run time (initial time to wait + duration) of all flows. The scenario will stop after the max_run_time has passed. Also flow which are not duration-based will be stopped.
If the max_run_time is not specified it will run for the the time of the flow with the longest run time (initial time to wait + duration). The scenario will wait (indefinitely) for any non duration-based flow to finish.

The duration parameter is kept for backward compatibility with older (beta) versions of the ByteBlower Test Framework. It will be removed definitely with the final version 1.0 release.

Parameters:

maximum_run_time (Optional[timedelta], optional) – maximum run time of the scenario, defaults to None
wait_for_finish (timedelta, optional) – Time to wait for sessions closing and final packets being received, defaults to timedelta(seconds=5)
duration (Optional[timedelta], optional) – Backward-compatible parameter for the max_run_time, defaults to None

Changed in version 1.2.0: The Scenario runtime has been improved with addition of ByteBlower Endpoint support.

Address resolution and NAT/NAPT discovery is now part of the “prepare flow configuration” step (see also Flow.prepare_configure() instead of flow construction (Flow.__init__()).

The scenario will wait for (maximum DEFAULT_RESULT_TIMEOUT) to let all ByteBlower Endpoint finish scenario execution and return their results to the Meeting Point.

property start_timestamp: datetime | None

Return the timestamp when the Scenario was started.

The start timestamp is the timestamp right before starting the flows. This is logged at the start of the Scenario.run() call.

Note

The time between endpoint and flow initialization is not taken into account here.

Returns:: Start timestamp of the last run
Return type:: Optional[datetime]

class byteblower_test_framework.all.Server

Bases: object

ByteBlower Server interface.

__init__(ip_or_host: str) → None

Connect to the ByteBlower server.

Parameters:: ip_or_host (str) – The connection address. This can be the hostname or IPv4/IPv6 address of the ByteBlower server.

property bb_server: ByteBlowerServer: Server object from the ByteBlower API.

property info: str: Return connection address this server.

release() → None

Release this host related resources used on the ByteBlower system.

Warning

Releasing resources related to traffic generation and analysis should be done first via the Scenario.release() and/or Flow.release().

Warning

Releasing endpoint resources should be done first via Port.release().

start() → None

Start all ByteBlower Ports configured on this server.

Warning

This call will start all traffic generation/analysis on all ByteBlowerPorts created for this Server.

This might not be intended when you run multiple test scenarios in parallel.

stop() → None

Stop all ByteBlower Ports configured on this server.

Warning

This call will stop all traffic generation/analysis on all ByteBlowerPorts created for this Server.

This might not be intended when you run multiple test scenarios in parallel.

class byteblower_test_framework.all.TCPCongestionAvoidanceAlgorithm

Bases: Enum

TCP Congestion Avoidance Algorithm.

Changed in version 1.2.0: Fixed for Python upper case naming convention.

NEW_RENO = 'new-reno'

NEW_RENO_WITH_CUBIC = 'new-reno-with-cubic'

NONE = 'None'

SACK = 'sack'

SACK_WITH_CUBIC = 'sack-with-cubic'

class byteblower_test_framework.all.UnitTestReport

Bases: object

Helper for generating JUnit XML test reports.

__init__() → None

Construct a new helper.

add_fail(step: str, message: str, stdout: str | None = None) → None

Add a failed test case.

Parameters:

step (str) – The step name (no spaces)
message (str) – The “fail” text
stdout (str | None) – The test standard output (log)

add_pass(step: str, message: str, stderr: str | None = None) → None

Add a succeeded test case.

Parameters:

step (str) – The step name (no spaces)
message (str) – The “pass” text (== test standard output / log)
stdout – The test standard output (log)

add_skipped(step: str, message: str, stdout: str | None = None, stderr: str | None = None) → None

Add a skipped test case.

Parameters:

step (str) – The step name (no spaces)
message (str) – The “skipped” text
stdout (str | None) – The test standard output (log)
stderr (str | None) – The test standard error (failure log)

save(name: str = 'report.xml') → None

Write the JUnit XML file.

This file can then be processed by the CI/CD/CT tool.

Parameters:: name (str) – Name of the JUnit XML output file.

set_subtest(subtest: str) → None

Start a new subtest; known as a test suite in JUnit XML.

Note

The previous subtest will be closed. When it did not contain any test cases, it won’t be added to the report.

Parameters:: subtest (str) – The subtest in the report

class byteblower_test_framework.all.VideoFlow

Bases: TcpFlow

Flow simulating video traffic.

__init__(source: Port, destination: Port, name: str | None = None, segment_size: int = 2000000, segment_duration: timedelta | float = datetime.timedelta(seconds=2, microseconds=500000), buffering_goal: timedelta | float = datetime.timedelta(seconds=60), play_goal: timedelta | float = datetime.timedelta(seconds=5), ip_dscp: int | None = None, ip_ecn: int | None = None, ip_traffic_class: int | None = None, **kwargs) → None

Create a video flow.

Parameters:

source (Port) – Sending endpoint of the data traffic
destination (Port) – Receiving endpoint of the data traffic
name (Optional[str], optional) – Name of this Flow, defaults to auto-generated name when set to None.
segment_size (int, optional) – size of video segment, defaults to 2*1000*1000
segment_duration (Union[timedelta, float], optional) – duration of video segment, defaults to timedelta(seconds=2.500)
buffering_goal (Union[timedelta, float], optional) – _description_, defaults to timedelta(seconds=60)
play_goal (Union[timedelta, float], optional) – _description_, defaults to timedelta(seconds=5)
ip_dscp (Optional[int], optional) – IP Differentiated Services Code Point (DSCP), mutual exclusive with ip_traffic_class, defaults to DEFAULT_IP_DSCP
ip_ecn (Optional[int], optional) – IP Explicit Congestion Notification (ECN), mutual exclusive with ip_traffic_class, defaults to DEFAULT_IP_ECN
ip_traffic_class (Optional[int], optional) – The IP traffic class value is used to specify the exact value of either the IPv4 ToS field or the IPv6 Traffic Class field, mutual exclusive with ip_dscp and ip_ecn, defaults to field value composed from ip_dscp and ip_ecn.

Raises:

FeatureNotSupported – When video flow is using ByteBlower Endpoint
ValueError – When an invalid value for segment_duration is used
ValueError – When an invalid value for buffering_goal is used
ValueError – When an invalid value for play_goal is used

analyse() → None

Pass or fail for this test.

property buffering_goal: timedelta

property duration: timedelta

Returns the duration of the Video flow.

Raises:: InfiniteDuration – The video flow always runs forever.
Returns:: duration of the flow.
Return type:: timedelta

property initial_time_to_wait: timedelta: Return the time to wait before the flow starts.

prepare_start(maximum_run_time: timedelta | None = None) → Iterable[SynchronizedExecutable]

Prepare the flow and its analysers to start traffic and analysis.

Warning

No more activities (like address / port discovery, …) allowed in the network under test.

Note

Virtual method with implementation. Should be called by child implementations.

Return type:: Iterable[SynchronizedExecutable]

process() → None

Note

Virtual method with implementation. Should be called by child implementations.

release() → None

Release all resources used on the ByteBlower system.

Releases all resources related to traffic generation and analysis.

Note

Virtual method with implementation. Should be called by child implementations.

Note

The resources related to endpoints and server themselves are not released.

property segment_duration: timedelta

property segment_size: int

updatestats() → None

Note

Virtual method with implementation. Should be called by child implementations.

class byteblower_test_framework.all.VoiceAnalyser

Bases: FlowAnalyser

Analyse the MOS of a voice flow.

Calculates the Mean Opinion Score (MOS) over the duration of the test.

The analyser also provides the RX and TX frame count and frame loss over the duration of the test.

This analyser is intended for use with a VoiceFlow.

Supports:

Analysis of a single flow

Warning

Does not support usage in AnalyserAggregator.

__init__(layer2_speed: Layer2Speed = Layer2Speed.frame, minimum_mos: float = 4)

Create the voice analyser.

Parameters:

layer2_speed (Layer2Speed, optional) – Configuration setting to select the layer 2 speed reporting, defaults to frame
minimum_mos (float, optional) – Minimum required MOS value, defaults to DEFAULT_MINIMUM_MOS

analyse() → None

Note

Virtual method.

details() → Mapping[str, Any] | None

Return the detailed analysis results in pandas-compatible objects.

Can be None if no detailed results are available or applicable.

Note

Virtual method.

Return type:: Mapping[str, Any] | None

property finished: bool: Return whether flow analysis has finished.

Note

Virtual method.

property flow: FrameBlastingFlow

Return Flow implementation.

Useful for correct type hinting.

initialize() → None

Configure the flow analyser.

Warning

No more activities (like address / port discovery, …) allowed in the network under test.

Note

Virtual method.

property log: str

Return the summary log text.

Note

Used for textual representation of the results in test reports.

Returns:: Summary log text.
Return type:: str

prepare_configure() → None

Prepare the flow analyser to be configured.

At this point, it is allowed to perform address resolution, port discovery, …

Note

Virtual method.

prepare_start(maximum_run_time: timedelta | None = None) → None

Prepare the flow analyser to start analysis.

Warning

No more activities (like address / port discovery, …) allowed in the network under test.

Note

Virtual method.

Parameters:: maximum_run_time (Optional[timedelta], optional) – Maximum run time of the scenario

process() → None

Note

Virtual method.

release() → None

Release all resources used on the ByteBlower system.

render() → str

Return the detailed analysis results in HTML format.

Note

Virtual method.

Return type:: str

updatestats() → None

Note

Virtual method.

class byteblower_test_framework.all.VoiceFlow

Bases: FrameBlastingFlow

Flow for simulating voice traffic.

The implementation simulates G.711 RTP traffic.

Create a G.711 voice flow with the given packetization.

Typical packetization times are:

20ms packetization
- Packet rate = 50 pps
- RTP packet size = 160 Bytes
10ms packetization
- Packet rate = 100 pps
- RTP packet size = 80 Bytes

Parameters:

source (Union[Port, Endpoint]) – Sending port of the voice stream
destination (Union[Port, Endpoint]) – Receiving port of the voice stream
name (Optional[str], optional) – Name of this Flow, defaults to auto-generated name when set to None.
packetization (Optional[int], optional) – Packetization time of the RTP packets in milliseconds, defaults to DEFAULT_G711_PACKETIZATION.
number_of_frames (Optional[int], optional) – Number of frames to transmit, defaults to DEFAULT_NUMBER_OF_FRAMES
duration (Optional[Union[timedelta, float, int]], optional) – Duration of the flow in seconds, defaults to None (use number_of_frames instead)
initial_time_to_wait (Optional[Union[timedelta, float, int]], optional) – Initial time to wait to start the flow. In seconds, defaults to None (start immediately)
udp_src (Optional[int], optional) – UDP src port, defaults to :const`UDP_DYNAMIC_PORT_START`
udp_dest (Optional[int], optional) – UDP dest port, defaults to :const`UDP_DYNAMIC_PORT_START`
ip_dscp (Optional[int], optional) – IP Differentiated Services Code Point (DSCP), mutual exclusive with ip_traffic_class, defaults to DEFAULT_IP_DSCP
ip_ecn (Optional[int], optional) – IP Explicit Congestion Notification (ECN), mutual exclusive with ip_traffic_class, defaults to DEFAULT_IP_ECN
ip_traffic_class (int | None) – The IP traffic class value is used to specify the exact value of either the IPv4 ToS field or the IPv6 Traffic Class field, mutual exclusive with ip_dscp and ip_ecn, defaults to field value composed from ip_dscp and ip_ecn.
enable_latency (Optional[bool], optional) – Enable latency tag in the packets (required for latency measurements at the destination port), defaults to False

Raises:

InvalidInput – When the type of the given source port is not supported.

byteblower_test_framework.all.configure_logging(): Configure logging for the used (low-level) frameworks.

Create a frame based on the (source) Port type.

Parameters:

source_port (Union[Port, Endpoint]) – Port which will be transmitting the Frame. Used to identify which Frame implementation we need (IPv4Frame or IPv6Frame)
length (Optional[int], optional) – Frame length. This is the layer 2 (Ethernet) frame length excluding Ethernet FCS and excluding VLAN tags, defaults to DEFAULT_FRAME_LENGTH
udp_src (Optional[int], optional) – UDP source port, defaults to UDP_DYNAMIC_PORT_START
udp_dest (Optional[int], optional) – UDP destination port, defaults to UDP_DYNAMIC_PORT_START
ip_dscp (Optional[int], optional) – IP Differentiated Services Code Point (DSCP), mutual exclusive with ip_traffic_class, defaults to DEFAULT_IP_DSCP
ip_ecn (Optional[int], optional) – IP Explicit Congestion Notification (ECN), mutual exclusive with ip_traffic_class, defaults to DEFAULT_IP_ECN
ip_traffic_class (Optional[int], optional) – The IP traffic class value is used to specify the exact value of either the IPv4 ToS field or the IPv6 Traffic Class field, mutual exclusive with ip_dscp and ip_ecn, defaults to field value composed from ip_dscp and ip_ecn.
latency_tag (bool, optional) – Enable latency tag generation in the Frame, defaults to False

Raises:

InvalidInput – When an unknown Port implementation is given.
InvalidInput – When invalid configuration values are given.
ConflictingInput – When invalid combination of configuration parameters is given

Returns:

New instance of an IPv4 or IPv6 Frame interface

Return type:

Union[Frame, MobileFrame]

Changed in version 1.2.0: Adding MobileFrame with ByteBlower Endpoint support.

Include Ethernet Layer 1/2 overhead in the value data.

When the value_data or count_data are DataFrame objects, they must be provided as a tuple of the DataFrame and a “key”. The “key” defines which column of the DataFrame to process.

With a value_data being a DataFrame, the “key” will also be used to filter the output. The returned value will be a DataFrame, only containing the (adjusted) values for column defined by the “key”.

For use with numeric values:

>>> total_tx_bytes = include_ethernet_overhead(
>>>     Layer2Speed.physical, total_tx_bytes, total_tx_packets
>>> )

For use with DataFrame values:

>>> df_rx_bytes = include_ethernet_overhead(
>>>     Layer2Speed.frame_with_fcs, (df_rx, 'Bytes interval'),
>>>     (df_rx, 'Packets interval')
>>> )

Note

If necessary, this function will create a copy of value_data to avoid SettingWithCopyWarning errors on DataFrame.

Parameters:

layer2_speed (Optional[Layer2Speed]) – Defines which overhead to include
value_data (ByteOrCountData) –
Input value(s).

Note

It MUST contain the number of Ethernet bytes excluding Ethernet FCS.
count_data (ByteOrCountData) – Packet count(s) for the values in value_data.

Raises:

ByteBlowerTestFrameworkException – When providing invalid input value(s) or count(s).

Returns:

(filtered) value_data adjusted to the layer2_speed.

Return type:

ByteOrCountStorage

byteblower_test_framework.all.log_api_error(func: Callable) → Callable

Decorate method or function to logs ByteBlower API errors.

Any exception will be (re-)raised.

Parameters:: func (Callable) – Function to decorate
Returns:: Decorated function
Return type:: Callable

byteblower_test_framework.all.string_array_to_int(value: int | str | bytes | bytearray) → int

Assure that a given value is an integer.

The value will be parsed from string if it is not already an integer type.

This function can help to allow script users to provide values in a human-readable format. For example IP DSCP values in hexadecimal string format in a JSON file. Where JSON only supports integer values in decimal format.

Parameters:: value (Union[int, str, bytes, bytearray]) – Value to convert
Returns:: Integer value converted from the input
Return type:: int