testplan.testing.multitest.driver.tcp package

Submodules

testplan.testing.multitest.driver.tcp.client module

TCPClient driver classes.

class testplan.testing.multitest.driver.tcp.client.TCPClient(name: str, host: str | ContextValue, port: int | str | ContextValue, interface: Tuple[str, int] | None = None, connect_at_start: bool = True, **options: Any)[source]

Bases: Driver

TCP client driver.

This is built on top of the testplan.common.utils.sockets.client.Client class, which provides equivalent functionality and may be used outside of MultiTest.

{emphasized_members_docs}

Parameters:

  • name – Name of TCPClient.

  • host – Target host name. This can be a ContextValue and will be expanded on runtime.

  • port – Target port number. This can be a ContextValue and will be expanded on runtime.

  • interface – Interface to bind to.

  • connect_at_start – Connect to server on start. Default: True

Also inherits all Driver options.

CONFIG

alias of TCPClientConfig

EXTRACTORS: List[BaseConnectionExtractor] = [<testplan.testing.multitest.driver.connection.connection_extractor.ConnectionExtractor object>]
STATUS

alias of ResourceStatus

abort() → None

Default abort policy. First abort all dependencies and then itself.

abort_dependencies() → Generator[Entity, None, None]

Returns an empty generator.

property aborted: bool

Returns if entity was aborted.

aborting() → None[source]

Abort logic that stops the client.

property active: bool

Entity not aborting/aborted.

property async_start: bool

Overrides the default async_start value in config.

property auto_start: bool

If False, the resource will not be automatically started by its parent (generally, a Environment object) while the parent is starting.

property cfg: Config

Configuration object.

close() → None[source]

Close connection.

connect() → None[source]

Connect client.

property connection_identifier: int | None
property context: Environment | None

Key/value pair information of a Resource.

context_input(exclude: list | None = None) → Dict[str, Any]

All attr of self in a dict for context resolution

define_runpath() → None

Define runpath directory based on parent object and configuration.

property errpath: str | None

Path for stderr file regexp matching.

extract_values() → bool | FailedAction

Extract matching values from input regex configuration options.

extracts: Dict[str, str]
failover() → Resource | None

API to create the failover resource, to be implemented in derived class

fetch_error_log() → List[str]

Fetch error message from the log files of driver, at first we can try self.errpath, if it does not exist, try self.logpath. Typically, several lines from the tail of file will be selected.

Returns:

text from log file

classmethod filter_locals(local_vars: Dict[str, Any]) → Dict[str, Any]

Filter out init params of None value, they will take default value defined in its ConfigOption object; also filter out special vars that are not init params from local_vars.

Parameters:

local_vars

force_started() → None

Change the status to STARTED (e.g. exception raised).

force_stop() → None

Change the status to STOPPED (e.g. exception raised).

get_connections() → List[BaseConnectionInfo]
property host: str | None

Target host name.

install_files() → None

Installs the files specified in the install_files parameter at the install target.

property is_alive: bool

Called to periodically poll the resource health. Default implementation assumes the resource is always healthy.

property local_host: str | None
property local_port: int | None
property logger: TestplanLogger

logger object

property logpath: str | None

Path for log regexp matching.

make_runpath_dirs() → None

Creates runpath related directories.

property name: str

Driver name.

property outpath: str | None

Path for stdout file regexp matching.

property parent: Entity | None

Returns parent Entity.

pause() → None

Pauses entity execution.

pausing() → None

Pause the resource.

pending_work() → bool

Resource has pending work.

property port: int | None

Client port number assigned.

post_start() → None

Steps to be executed right after resource is started.

post_stop() → None

Steps to be executed right after resource is stopped.

pre_start() → None

Steps to be executed right before resource starts.

pre_stop() → None

Steps to be executed right before resource stops.

receive(size: int = 1024, timeout: int = 30) → bytes | None[source]

Receive bytes from the given connection.

receive_text(standard: str = 'utf-8', **kwargs: Any) → str[source]

Calls TCPClient.receive and decodes received bytes.

reconnect() → None[source]

Client reconnect.

register_failover(klass: Type[Entity], params: dict) → None

Register a failover class to instantiate if resource start fails.

Parameters:

  • klass – failover class

  • params – parameters for failover class __init__ method

property report: ReportLink

A handle to access the report via recursive parent

restart() → None

Stop and start the resource.

resume() → None

Resumes entity execution.

resuming() → None

Resume the resource.

property runpath: str

Path to be used for temp/output files by entity.

property scratch: str

Path to be used for temp files by entity.

send(msg: bytes) → int[source]

Sends bytes.

Parameters:

msg – Message to be sent

Returns:

Number of bytes sent

send_text(msg: str, standard: str = 'utf-8') → int[source]

Encodes to bytes and calls TCPClient.send.

send_tsp(msg: bytes) → Tuple[float, int][source]

Sends bytes and returns also timestamp sent.

Parameters:

msg – Message to be sent

Returns:

Timestamp when msg sent (in microseconds from epoch) and number of bytes sent

property server_port: int | None
start() → None

Triggers the start logic of a Resource by executing :py:meth: Resource.starting <testplan.common.entity.base.Resource.starting> method.

property start_timeout: float
started_check() → bool | FailedAction

Predicate indicating whether driver has fully started.

Default implementation tests whether certain pattern exists in driver loggings, always returns True if no pattern is required.

property started_check_interval: float | Tuple[float, float]

Driver started check interval. In practice this value is lower-bounded by 0.1 seconds.

starting() → None[source]

Start the TCP client and optionally connect to host/post.

property status: EntityStatus

Status object.

stop() → None

Triggers the stop logic of a Resource by executing :py:meth: Resource.stopping <testplan.common.entity.base.Resource.stopping> method.

property stop_timeout: float
stopped_check() → bool | FailedAction

Predicate indicating whether driver has fully stopped.

Default implementation immediately returns True.

property stopped_check_interval: float | Tuple[float, float]

Driver stopped check interval.

stopped_check_with_watch(watch: Any) → bool | FailedAction
stopping() → None[source]

Close the client connection.

property timer: Timer
uid() → str

Driver uid.

wait(target_status: str | None, timeout: int | None = None) → None

Wait until objects status becomes target status.

Parameters:

  • target_status (str) – expected status

  • timeout (int or NoneType) – timeout in seconds

class testplan.testing.multitest.driver.tcp.client.TCPClientConfig(**options: Any)[source]

Bases: DriverConfig

Configuration object for TCPClient driver.

classmethod build_schema() → Schema

Build a validation schema using the config options defined in this class and its parent classes.

denormalize() → Config

Create new config object that inherits all explicit attributes from its parents as well.

get_local(name: str, default: Any = None) → Any

Returns a local config setting (not from container)

classmethod get_options() → Dict[Any, Any][source]

Schema for options validation and assignment of default values.

ignore_extra_keys = False
property parent: Config | None

Returns the parent configuration.

set_local(name: str, value: Any) → None

set without any check

testplan.testing.multitest.driver.tcp.server module

TCPServer driver classes.

class testplan.testing.multitest.driver.tcp.server.TCPServer(name: str, host: str | ContextValue | None = 'localhost', port: int | str | ContextValue | None = 0, **options: Any)[source]

Bases: Driver

Driver for a server that can send and receive messages over TCP. Supports multiple connections.

This is built on top of the testplan.common.utils.sockets.server.Server class, which provides equivalent functionality and may be used outside of MultiTest.

{emphasized_members_docs}

Parameters:

  • name (str) – Name of TCPServer.

  • host (str) – Host name to bind to. Default: ‘localhost’

  • port (int) – Port number to bind to. Default: 0 (Random port)

Also inherits all Driver options.

CONFIG

alias of TCPServerConfig

EXTRACTORS: List[BaseConnectionExtractor] = [<testplan.testing.multitest.driver.connection.connection_extractor.ConnectionExtractor object>]
STATUS

alias of ResourceStatus

abort() → None

Default abort policy. First abort all dependencies and then itself.

abort_dependencies() → Generator[Entity, None, None]

Returns an empty generator.

property aborted: bool

Returns if entity was aborted.

aborting() → None[source]

Abort logic that stops the server.

accept_connection(timeout: int = 10) → Any[source]

Accepts a connection in the order in which they were received. Return the index of the connection, which can be used to send and receive messages using that connection. If no connection is already available or becomes available in the given timeout, then the method returns -1.

Parameters:

  • timeout (int) – Timeout to wait for receiving connection.

  • accept_connection_sleep (float) – Sleep time to retry accept connection.

Returns:

Index of connection

Return type:

int

property active: bool

Entity not aborting/aborted.

property async_start: bool

Overrides the default async_start value in config.

property auto_start: bool

If False, the resource will not be automatically started by its parent (generally, a Environment object) while the parent is starting.

property cfg: Config

Configuration object.

close_connection(conn_idx: int) → None[source]

Unregister, close and remove connection with given connection index

Parameters:

conn_idx (int) – Connection index of connection to be removed

Returns:

None

Return type:

NoneType

property connection_identifier: int | None
property context: Environment | None

Key/value pair information of a Resource.

context_input(exclude: list | None = None) → Dict[str, Any]

All attr of self in a dict for context resolution

define_runpath() → None

Define runpath directory based on parent object and configuration.

property errpath: str | None

Path for stderr file regexp matching.

extract_values() → bool | FailedAction

Extract matching values from input regex configuration options.

extracts: Dict[str, str]
failover() → Resource | None

API to create the failover resource, to be implemented in derived class

fetch_error_log() → List[str]

Fetch error message from the log files of driver, at first we can try self.errpath, if it does not exist, try self.logpath. Typically, several lines from the tail of file will be selected.

Returns:

text from log file

classmethod filter_locals(local_vars: Dict[str, Any]) → Dict[str, Any]

Filter out init params of None value, they will take default value defined in its ConfigOption object; also filter out special vars that are not init params from local_vars.

Parameters:

local_vars

force_started() → None

Change the status to STARTED (e.g. exception raised).

force_stop() → None

Change the status to STOPPED (e.g. exception raised).

get_connections() → List[BaseConnectionInfo]
property host: str | None

Target host name.

install_files() → None

Installs the files specified in the install_files parameter at the install target.

property is_alive: bool

Called to periodically poll the resource health. Default implementation assumes the resource is always healthy.

property local_host: str | None
property local_port: int | None
property logger: TestplanLogger

logger object

property logpath: str | None

Path for log regexp matching.

make_runpath_dirs() → None

Creates runpath related directories.

property name: str

Driver name.

property outpath: str | None

Path for stdout file regexp matching.

property parent: Entity | None

Returns parent Entity.

pause() → None

Pauses entity execution.

pausing() → None

Pause the resource.

pending_work() → bool

Resource has pending work.

property port: int | None

Port number assigned.

post_start() → None

Steps to be executed right after resource is started.

post_stop() → None

Steps to be executed right after resource is stopped.

pre_start() → None

Steps to be executed right before resource starts.

pre_stop() → None

Steps to be executed right before resource stops.

receive(size: int | None = None, conn_idx: int | None = None, timeout: int | None = 30) → bytes | None[source]

Receive bytes from the given connection.

receive_text(standard: str = 'utf-8', **kwargs: Any) → str[source]

Calls TCPServer.receive and decodes received bytes.

register_failover(klass: Type[Entity], params: dict) → None

Register a failover class to instantiate if resource start fails.

Parameters:

  • klass – failover class

  • params – parameters for failover class __init__ method

property report: ReportLink

A handle to access the report via recursive parent

restart() → None

Stop and start the resource.

resume() → None

Resumes entity execution.

resuming() → None

Resume the resource.

property runpath: str

Path to be used for temp/output files by entity.

property scratch: str

Path to be used for temp files by entity.

send(msg: bytes, conn_idx: int | None = None, timeout: int = 30) → Any[source]

Send the given message through the given connection.

Parameters:

  • msg (bytes) – message to be sent

  • conn_idx (int) – Index of connection to send to

  • timeout (int) – Timeout in seconds for sending all bytes

Returns:

Number of bytes sent

Return type:

int

send_text(msg: str, standard: str = 'utf-8', **kwargs: Any) → Any[source]

Encodes to bytes and calls TCPServer.send.

property socket: Any

Returns the underlying socket object

start() → None

Triggers the start logic of a Resource by executing :py:meth: Resource.starting <testplan.common.entity.base.Resource.starting> method.

property start_timeout: float
started_check() → bool | FailedAction

Predicate indicating whether driver has fully started.

Default implementation tests whether certain pattern exists in driver loggings, always returns True if no pattern is required.

property started_check_interval: float | Tuple[float, float]

Driver started check interval. In practice this value is lower-bounded by 0.1 seconds.

starting() → None[source]

Starts the TCP server.

property status: EntityStatus

Status object.

stop() → None

Triggers the stop logic of a Resource by executing :py:meth: Resource.stopping <testplan.common.entity.base.Resource.stopping> method.

property stop_timeout: float
stopped_check() → bool | FailedAction

Predicate indicating whether driver has fully stopped.

Default implementation immediately returns True.

property stopped_check_interval: float | Tuple[float, float]

Driver stopped check interval.

stopped_check_with_watch(watch: Any) → bool | FailedAction
stopping() → None[source]

Stops the TCP server.

property timer: Timer
uid() → str

Driver uid.

wait(target_status: str | None, timeout: int | None = None) → None

Wait until objects status becomes target status.

Parameters:

  • target_status (str) – expected status

  • timeout (int or NoneType) – timeout in seconds

class testplan.testing.multitest.driver.tcp.server.TCPServerConfig(**options: Any)[source]

Bases: DriverConfig

Configuration object for TCPServer driver.

classmethod build_schema() → Schema

Build a validation schema using the config options defined in this class and its parent classes.

denormalize() → Config

Create new config object that inherits all explicit attributes from its parents as well.

get_local(name: str, default: Any = None) → Any

Returns a local config setting (not from container)

classmethod get_options() → Dict[Any, Any][source]

Schema for options validation and assignment of default values.

ignore_extra_keys = False
property parent: Config | None

Returns the parent configuration.

set_local(name: str, value: Any) → None

set without any check

Module contents

TCP communication protocol drivers.