testplan.testing.multitest.driver package

Subpackages

Submodules

testplan.testing.multitest.driver.app module

Generic application driver.

class testplan.testing.multitest.driver.app.App(name: str, binary: str, pre_args: List[str | ContextValue] | str | ContextValue = None, args: List[str | ContextValue] | str | ContextValue = None, shell: bool = False, env: Dict[str, str] = None, binary_strategy: Literal['copy', 'link', 'noop'] = 'link', logname: str = None, app_dir_name: str = None, working_dir: str = None, expected_retcode: int = None, stop_signal: Signals | None = None, stop_timeout: float = 5, binary_log: bool = False, **options)[source]

Bases: Driver

Binary application driver.

{emphasized_members_docs}

Parameters:

  • name – Driver name. Also uid.

  • binary – Path to the application binary.

  • pre_args – Arguments to be prepended to binary command. An argument can be a ContextValue and will be expanded on runtime.

  • args – Arguments to be appended to binary command. An argument can be a ContextValue and will be expanded on runtime.

  • shell – Invoke shell for command execution.

  • env – Environmental variables to be made available to child process; context value (when referring to other driver) and jinja2 template (when referring to self) will be resolved.

  • binary_strategy – Whether to copy / link binary to runpath.

  • logname – Base name of driver logfile under app_path, in which Testplan will look for log_regexps as driver start-up condition. Default to “stdout” (to match the output stream of binary).

  • app_dir_name – Application directory name.

  • working_dir – Application working directory. Default: runpath

  • expected_retcode – the expected return code of the subprocess. Default value is None meaning it won’t be checked. Set it to 0 to ennsure the driver is always gracefully shut down.

  • stop_signal – Shutdown signal to be sent to subprocess.

  • stop_timeout – Timeout for graceful shutdown (in seconds).

  • binary_log – if True the log_matcher will handle the logfile as binary, and need to use binary regexps. Default value is False.

Also inherits all Driver options.

CONFIG

alias of AppConfig

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

alias of ResourceStatus

abort()

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

abort_dependencies()

Returns an empty generator.

property aborted

Returns if entity was aborted.

aborting() → None[source]

Abort logic to force kill the child binary.

property active

Entity not aborting/aborted.

property alive_child_procs: List[Process]
property app_path: str

Application directory path.

property async_start: bool

Overrides the default async_start value in config.

property auto_start

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

property binary: str

The actual binary to execute, might be copied/linked to runpath

property binpath: str

‘bin’ directory under runpath.

property cfg

Configuration object.

property cmd: str

Command that starts the application.

property context

Key/value pair information of a Resource.

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

All attr of self in a dict for context resolution

define_runpath()

Define runpath directory based on parent object and configuration.

property env: Dict[str, str] | None

Environment variables.

property errpath: str

Path for stderr file regex matching.

property etcpath: str

‘etc’ directory under runpath.

extract_values() → bool | FailedAction

Extract matching values from input regex configuration options.

failover() → 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)

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()

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

force_stop()

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

get_connections() → List[BaseConnectionInfo]
property hostname: str
Returns:

hostname where the ETSApp is running

install_files() → None

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

property is_alive

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

property log_matcher: LogMatcher

Create if not exist and return the LogMatcher object that reads the log / stdout of the driver.

Returns:

LogMatcher instance

property logger: TestplanLogger

logger object

property logname: str

Configured logname.

property logpath: str

Path for log regex matching.

make_runpath_dirs() → None[source]

Create mandatory directories and install files from given templates using the drivers context before starting the application binary.

property name: str

Driver name.

property outpath: str

Path for stdout file regex matching.

property parent

Returns parent Entity.

pause()

Pauses entity execution.

pausing()

Pause the resource.

pending_work()

Resource has pending work.

property pid: int | None

Return pid of the child process if available, None otherwise.

post_start()

Steps to be executed right after resource is started.

post_stop()[source]

Steps to be executed right after resource is stopped.

pre_start() → None

Steps to be executed right before resource starts.

pre_stop()

Steps to be executed right before resource stops.

register_failover(klass: 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

A handle to access the report via recursive parent

property resolved_bin: str

Resolved binary path from self.cfg.binary

restart(clean: bool = True) → None[source]

Stop the driver, archive the app_dir or rename std/log, and then restart the driver.

Parameters:

clean – if set to True, perform a ‘clean’ restart where all persistence is deleted, else a normal restart.

resume()

Resumes entity execution.

resuming()

Resume the resource.

property retcode: int | None

Return return code of the app process or None.

property runpath

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

property scratch

Path to be used for temp files by entity.

start()

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[source]

Predicate indicating whether a binary in a subprocess has started. Tests whether the return code is zero if the underlying binary has finished execution, otherwise tests if user-specified pattern exists in driver logs.

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 application binary.

property status

Status object.

stop()

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[source]

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) → bool | FailedAction[source]
stopping() → None[source]

Stops the application binary process.

property timer
uid() → str

Driver uid.

wait(target_status, timeout=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.app.AppConfig(**options)[source]

Bases: DriverConfig

Configuration object for App resource.

classmethod build_schema()

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

denormalize()

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

get_local(name, default=None)

Returns a local config setting (not from container)

classmethod get_options()[source]

Schema for options validation and assignment of default values.

ignore_extra_keys = False
property parent

Returns the parent configuration.

set_local(name, value)

set without any check

exception testplan.testing.multitest.driver.app.OrphanedProcessException(driver, procs)[source]

Bases: Exception

Exception raised when there are orphaned processes after stopping the driver.

add_note(object, /)

Exception.add_note(note) – add a note to the exception

args
with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

testplan.testing.multitest.driver.base module

Driver base class module.

class testplan.testing.multitest.driver.base.Driver(name: str, install_files: ~typing.List[str | ~typing.Tuple] = None, timeout: int = 300, log_regexps: ~typing.List[~typing.Pattern] = None, stdout_regexps: ~typing.List[~typing.Pattern] = None, stderr_regexps: ~typing.List[~typing.Pattern] = None, file_logger: str = None, async_start: ~testplan.common.config.base.UNSET_T | bool = <testplan.common.config.base.UNSET_T object>, report_errors_from_logs: bool = False, error_logs_max_lines: int = 10, pre_start: ~typing.Callable = None, post_start: ~typing.Callable = None, pre_stop: ~typing.Callable = None, post_stop: ~typing.Callable = None, **options)[source]

Bases: Resource

Driver base class providing common functionality.

{emphasized_members_docs}

Parameters:

  • name – driver name also used as UID

  • install_files – list of files to be installed

  • timeout – status check timeout in seconds

  • log_regexps – regexps to be matched in logfile

  • stdout_regexps – regexps to be matched in stdout file

  • stderr_regexps – regexps to be matched in stderr file

  • file_logger – filepath for driver log, defaults to top level TP log

  • async_start – whether to allow async start in environment

  • report_errors_from_logs – whether to log the tail of stdout/stderr/logfile logs upon start/stop exception

  • error_logs_max_lines – number of lines to be logged from the tail of stdout/stderr/logfile logs if report_errors_from_logs is True

  • path_cleanup – whether to remove existing runpath elements

  • pre_start – callable to execute before starting the driver

  • post_start – callable to execute after the driver is started

  • pre_stop – callable to execute before stopping the driver

  • pre_stop – callable to execute after the driver is stopped

Also inherits all Resource options.

CONFIG

alias of DriverConfig

EXTRACTORS: List[BaseConnectionExtractor] = []
aborting() → None[source]

Triggers driver abort.

property async_start: bool

Overrides the default async_start value in config.

property errpath

Path for stderr file regexp matching.

extract_values() → bool | FailedAction[source]

Extract matching values from input regex configuration options.

fetch_error_log() → List[str][source]

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

get_connections() → List[BaseConnectionInfo][source]
install_files() → None[source]

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

property logpath

Path for log regexp matching.

property name: str

Driver name.

property outpath

Path for stdout file regexp matching.

pre_start() → None[source]

Steps to be executed right before resource starts.

property start_timeout: float
started_check() → bool | FailedAction[source]

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]

Triggers driver start.

property stop_timeout: float
stopped_check() → bool | FailedAction[source]

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) → bool | FailedAction[source]
stopping() → None[source]

Triggers driver stop.

uid() → str[source]

Driver uid.

wait(target_status, timeout=None)[source]

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.base.DriverConfig(**options)[source]

Bases: ResourceConfig

Configuration object for Driver resource.

classmethod get_options()[source]

Schema for options validation and assignment of default values.

testplan.testing.multitest.driver.sqlite module

Small wrapper driver around sqlite3 library.

class testplan.testing.multitest.driver.sqlite.Sqlite3(name: str, db_path: str, connect_at_start: bool = True, **options)[source]

Bases: Driver

Basic sqlite3 driver to add to a MultiTest environment, connect to a database and perform sql queries etc.

{emphasized_members_docs}

Parameters:

  • db_path (str) – Path to the database file to connect to. In case a relative path is provided it will be appended to the runpath.

  • connect_at_start (bool) – Connect to the database when driver starts. Default: True

CONFIG

alias of Sqlite3Config

EXTRACTORS: List[BaseConnectionExtractor] = []
STATUS

alias of ResourceStatus

abort()

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

abort_dependencies()

Returns an empty generator.

property aborted

Returns if entity was aborted.

aborting(*args, **kwargs)[source]

Abort the driver.

property active

Entity not aborting/aborted.

property async_start: bool

Overrides the default async_start value in config.

property auto_start

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

property cfg

Configuration object.

commit()[source]

Commit db changes.

commit_at_exit()[source]

Context manager to perform operations and .commit() at exit.

connect()[source]

Connect to the database and set the internal db cursor.

property context

Key/value pair information of a Resource.

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

All attr of self in a dict for context resolution

property db_path

Database file path.

define_runpath()

Define runpath directory based on parent object and configuration.

property errpath

Path for stderr file regexp matching.

execute(*args, **kwargs)[source]

Invoke cursor execute.

executemany(*args)[source]

Invoke cursor executemany.

extract_values() → bool | FailedAction

Extract matching values from input regex configuration options.

failover() → 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

fetch_table(table, columns=None)[source]

Fetch a table from the db. The first row will be the column names and the following rows will be the table rows. Returns a table like:

[
  ['symbol', 'amount'],
  ['AAPL', 12],
  ['GOOG', 21],
  ['FB', 32],
  ['AMZN', 5],
  ['MSFT', 42]
]
Parameters:

  • table (str) – Table name in the db.

  • columns (list of str) – Names of columns to be fetched.

Returns:

The table contents.

Return type:

list of list of values.

fetchall()[source]

Invoke cursor fetchall.

fetchone()[source]

Invoke cursor fetchone.

classmethod filter_locals(local_vars)

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()

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

force_stop()

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

get_connections() → List[BaseConnectionInfo]
install_files() → None

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

property is_alive

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

property logger: TestplanLogger

logger object

property logpath

Path for log regexp matching.

make_runpath_dirs()

Creates runpath related directories.

property name: str

Driver name.

property outpath

Path for stdout file regexp matching.

property parent

Returns parent Entity.

pause()

Pauses entity execution.

pausing()

Pause the resource.

pending_work()

Resource has pending work.

post_start()

Steps to be executed right after resource is started.

post_stop()

Steps to be executed right after resource is stopped.

pre_start() → None

Steps to be executed right before resource starts.

pre_stop()

Steps to be executed right before resource stops.

register_failover(klass: 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

A handle to access the report via recursive parent

restart()

Stop and start the resource.

resume()

Resumes entity execution.

resuming()

Resume the resource.

property runpath

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

property scratch

Path to be used for temp files by entity.

start()

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()[source]

Start the driver.

property status

Status object.

stop()

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) → bool | FailedAction
stopping()[source]

Stop the driver.

property timer
uid() → str

Driver uid.

wait(target_status, timeout=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.sqlite.Sqlite3Config(**options)[source]

Bases: DriverConfig

Configuration object for Sqlite3 resource.

classmethod build_schema()

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

denormalize()

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

get_local(name, default=None)

Returns a local config setting (not from container)

classmethod get_options()[source]

Schema for options validation and assignment of default values.

ignore_extra_keys = False
property parent

Returns the parent configuration.

set_local(name, value)

set without any check

testplan.testing.multitest.driver.kafka module

Driver for Kafka server

class testplan.testing.multitest.driver.kafka.KafkaStandalone(name: str, cfg_template: str, binary: str = '/opt/kafka/bin/kafka-server-start.sh', host: str | None = None, port: int = 0, **options)[source]

Bases: App

Driver for starting a Kafka instance in standalone mode.

{emphasized_members_docs}

Parameters:

  • cfg_template (str) – Kafka config file template.

  • binary (str) – kafka-server-start.sh file path.

  • port (int) – Kafka listen port.

  • env (dict) – Environmental variables to be made available to Zookeeper process.

CONFIG

alias of KafkaStandaloneConfig

property cmd: List[str]

Command that starts the application.

property host: str

Host to bind to.

property port: int

Port to listen on.

post_start()[source]

Steps to be executed right after resource is started.

pre_start()[source]

Steps to be executed right before resource starts.

class testplan.testing.multitest.driver.kafka.KafkaStandaloneConfig(**options)[source]

Bases: AppConfig

Configuration object for KafkaStandalone resource.

classmethod get_options()[source]

Schema for options validation and assignment of default values.

testplan.testing.multitest.driver.zookeeper module

Driver for Zookeeper server

class testplan.testing.multitest.driver.zookeeper.ZookeeperStandalone(name: str, cfg_template: str, binary: str = '/usr/share/zookeeper/bin/zkServer.sh', host: str | None = None, port: int = 2181, env: dict | None = None, **options)[source]

Bases: Driver

Driver for starting a Zookeeper instance in standalone mode.

{emphasized_members_docs}

Parameters:

  • template (str) – Zookeeper config file template.

  • binary (str) – zkServer.sh file path.

  • port (int) – Zookeeper listen port. Zookeeper doesn’t support random port

  • env (dict) – Environmental variables to be made available to Zookeeper process.

CONFIG

alias of ZookeeperStandaloneConfig

EXTRACTORS: List[BaseConnectionExtractor] = [<testplan.testing.multitest.driver.connection.connection_extractor.ConnectionExtractor object>]
property connection_identifier
property connection_str: str

Connection string.

property env: Dict[str, str]

Environment variables.

property host: str

Host to bind to.

property local_host
property local_port
property port: int

Port to listen on.

post_start()[source]

Steps to be executed right after resource is started.

pre_start()[source]

Create mandatory directories and install files from given templates using the drivers context before starting zookeeper.

starting()[source]

Starts the Zookeeper instance.

stopping()[source]

Stops the Zookeeper instance.

class testplan.testing.multitest.driver.zookeeper.ZookeeperStandaloneConfig(**options)[source]

Bases: DriverConfig

Configuration object for ZookeeperStandalone resource.

classmethod get_options()[source]

Schema for options validation and assignment of default values.

Module contents

Drivers modules.

This is actually a Testplan level feature, and this subpackage could be moved to testplan.common.driver in the future.

class testplan.testing.multitest.driver.Driver(name: str, install_files: ~typing.List[str | ~typing.Tuple] = None, timeout: int = 300, log_regexps: ~typing.List[~typing.Pattern] = None, stdout_regexps: ~typing.List[~typing.Pattern] = None, stderr_regexps: ~typing.List[~typing.Pattern] = None, file_logger: str = None, async_start: ~testplan.common.config.base.UNSET_T | bool = <testplan.common.config.base.UNSET_T object>, report_errors_from_logs: bool = False, error_logs_max_lines: int = 10, pre_start: ~typing.Callable = None, post_start: ~typing.Callable = None, pre_stop: ~typing.Callable = None, post_stop: ~typing.Callable = None, **options)[source]

Bases: Resource

Driver base class providing common functionality.

{emphasized_members_docs}

Parameters:

  • name – driver name also used as UID

  • install_files – list of files to be installed

  • timeout – status check timeout in seconds

  • log_regexps – regexps to be matched in logfile

  • stdout_regexps – regexps to be matched in stdout file

  • stderr_regexps – regexps to be matched in stderr file

  • file_logger – filepath for driver log, defaults to top level TP log

  • async_start – whether to allow async start in environment

  • report_errors_from_logs – whether to log the tail of stdout/stderr/logfile logs upon start/stop exception

  • error_logs_max_lines – number of lines to be logged from the tail of stdout/stderr/logfile logs if report_errors_from_logs is True

  • path_cleanup – whether to remove existing runpath elements

  • pre_start – callable to execute before starting the driver

  • post_start – callable to execute after the driver is started

  • pre_stop – callable to execute before stopping the driver

  • pre_stop – callable to execute after the driver is stopped

Also inherits all Resource options.

CONFIG

alias of DriverConfig

EXTRACTORS: List[BaseConnectionExtractor] = []
aborting() → None[source]

Triggers driver abort.

property async_start: bool

Overrides the default async_start value in config.

property errpath

Path for stderr file regexp matching.

extract_values() → bool | FailedAction[source]

Extract matching values from input regex configuration options.

fetch_error_log() → List[str][source]

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

get_connections() → List[BaseConnectionInfo][source]
install_files() → None[source]

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

property logpath

Path for log regexp matching.

property name: str

Driver name.

property outpath

Path for stdout file regexp matching.

pre_start() → None[source]

Steps to be executed right before resource starts.

property start_timeout: float
started_check() → bool | FailedAction[source]

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]

Triggers driver start.

property stop_timeout: float
stopped_check() → bool | FailedAction[source]

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) → bool | FailedAction[source]
stopping() → None[source]

Triggers driver stop.

uid() → str[source]

Driver uid.

wait(target_status, timeout=None)[source]

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.DriverConfig(**options)[source]

Bases: ResourceConfig

Configuration object for Driver resource.

classmethod get_options()[source]

Schema for options validation and assignment of default values.