testplan.common.remote package

Submodules

testplan.common.remote.remote_resource module

class testplan.common.remote.remote_resource.RemoteResource(remote_host: str, ssh_port: int = 22, ssh_cmd: Callable = <function ssh_cmd>, copy_cmd: Callable = <function copy_cmd>, workspace: str | None = None, workspace_exclude: List[str] | None = None, remote_runpath: str | None = None, remote_workspace: str | None = None, clean_remote: bool = False, push: List[str | Tuple] | None = None, push_exclude: List[str] | None = None, delete_pushed: bool = False, fetch_runpath: bool = True, fetch_runpath_exclude: List[str] | None = None, pull: List[str] | None = None, pull_exclude: List[str] | None = None, env: Dict[str, str] | None=None, setup_script: List[str] | None = None, paramiko_config: dict | None = None, remote_runtime_builder: RuntimeBuilder | None = None, status_wait_timeout: int = 600, **options: Any)

Bases: Entity

Common base class for Resource that runs on remote host. Handles logistics including copy/link workspace and testplan lib to remote, creating runpath on remote, and fetching back files from remote etc.

Parameters:

• remote_host – Remote hostname to connect to.

• ssh_port – The ssh port number of remote host, default is 22.

• ssh_cmd – callable that prefix a command with ssh binary and options

• copy_cmd – callable that returns the cmdline to do copy on remote host

• workspace – Current project workspace to be transferred, default is pwd.

• workspace_exclude – Patterns to exclude files when pushing workspace.

• remote_runpath – Root runpath on remote host, default is same as local (Linux->Linux) or /var/tmp/$USER/testplan/$plan_name (Window->Linux).

• remote_workspace – The path of the workspace on remote host, default is fetched_workspace under remote_runpath

• clean_remote – Deleted root runpath on remote at exit.

• push – Files and directories to push to the remote.

• push_exclude – Patterns to exclude files on push stage.

• delete_pushed – Deleted pushed files on remote at exit.

• fetch_runpath – The flag of fetch remote resource’s runpath, default to True.

• fetch_runpath_exclude – Exclude files matching PATTERN.

• pull – Files and directories to be pulled from the remote at the end.

• pull_exclude – Patterns to exclude files on pull stage.

• env – Environment variables to be propagated.

• setup_script – Script to be executed on remote as very first thing.

• paramiko_config – Paramiko SSH client extra configuration.

• remote_runtime_builder – RuntimeBuilder instance to prepare remote python env. Default is SourceTransferBuilder().

• status_wait_timeout – remote resource start/stop timeout, default is 600.

CONFIG

alias of RemoteResourceConfig

property error_exec: list

property remote_python_bin: str

class testplan.common.remote.remote_resource.RemoteResourceConfig(**options: Any)

Bases: UnboundRemoteResourceConfig

classmethod get_options() → Dict[Any, Any]

Schema for options validation and assignment of default values.

class testplan.common.remote.remote_resource.UnboundRemoteResourceConfig(**options: Any)

Bases: EntityConfig

classmethod get_options() → Dict[Any, Any]

Schema for options validation and assignment of default values.

class testplan.common.remote.remote_resource.WorkerSetupMetadata

Bases: object

Metadata used on worker setup stage execution. Pushed dirs and files will be registered for deletion at exit.

testplan.common.remote.remote_runtime module

python runtime environment builder for remote test execution

pybin refers to the path to python binary pyenv refers to the python environment, e.g. venv or system env

XXX: support pathlib

class testplan.common.remote.remote_runtime.PipBasedBuilder(**options: Any)

Bases: RuntimeBuilder

pip-based remote python runtime environment builder, which would install the exact same packages as local on remote machine using pip-compatible interface provided by the uv python package tool

Parameters:

• transfer_exclude – list of glob patterns to exclude from transfer during remote runtime environment building

• python_base_bin – python base binary to create venv from or use directly on remote

• venv_path – user-specified full venv path on remote

• reuse_venv_if_exist – if venv_path specified and exists, reuse it without deletion and re-creation, while packages still uploaded and installed

• skip_install_deps_if_exist – if venv_path specified and exists, skip packages installation, useful if packages already installed in venv and no dependency changed since last run. note no dependency check is performed, use with caution.

• use_sys_env – use system python environment directly without venv creation

• extra_install_env_vars – dict of extra environment variables to set during uv pip install on remote

• overridden_deps – list of package requirement strings to override (replace) the dependencies detected from local venv, should be alike the format of uv pip freeze output, e.g. ["packageA==1.2.3", "packageB @ file:///path/to/packageB", "packageC", "packageA!=1.2.3+local", ...]

CONFIG

alias of PipBasedBuilderConfig

bootstrap(*args: Any, **kwargs: Any) → None

runtime initialization with info from parent RemoteResource

static deduce_python_bin(env_prefix: str) → str

get_remote_rpyc_bin() → str

return rpyc binary path on remote side

static group_freezed(packages: List[str]) → Tuple[List[str], List[str]]

local_export_pyenv() → List[Tuple[str, str]]

export pyenv on local side, return a list of (local_path, remote_path) pairs that need to be transferred to remote side

remote_prepare_pybin() → str

prepare pybin on remote side

Returns:

python binary path on remote to be used to execute tests

remote_setup_pyenv(remote_paths: List[str]) → str

setup pyenv on remote side

Parameters:

remote_paths – list of paths on remote that are transferred from local

Returns:

path to testplan parent dir on remote, for sys.path alteration

remote_teardown_pyenv() → None

teardown pyenv on remote side

class testplan.common.remote.remote_runtime.PipBasedBuilderConfig(**options: Any)

Bases: RuntimeBuilderConfig

config class for PipBasedBuilder

classmethod get_options() → Dict[Any, Any]

Override this classmethod to provide extra config arguments.

class testplan.common.remote.remote_runtime.RuntimeBuilder(**options: Any)

Bases: Entity, ABC

common parent abstract class for remote python runtime environment builder

methods prefixed with “remote_” are executed on remote methods prefixed with “local_” are executed on local

bootstrap(local_runpath: str, remote_runpath: str, local_cmd_exec: Callable[[...], tuple[int, str, str]], remote_cmd_exec: Callable[[...], tuple[int, str, str]], parent_cfg: Config) → None

runtime initialization with info from parent RemoteResource

abstractmethod get_remote_rpyc_bin() → str

return rpyc binary path on remote side

abstractmethod local_export_pyenv() → list[tuple[str, str]]

export pyenv on local side, return a list of (local_path, remote_path) pairs that need to be transferred to remote side

abstractmethod remote_prepare_pybin() → str

prepare pybin on remote side

Returns:

python binary path on remote to be used to execute tests

abstractmethod remote_setup_pyenv(remote_paths: list[str]) → str

setup pyenv on remote side

Parameters:

remote_paths – list of paths on remote that are transferred from local

Returns:

path to testplan parent dir on remote, for sys.path alteration

abstractmethod remote_teardown_pyenv() → None

teardown pyenv on remote side

class testplan.common.remote.remote_runtime.RuntimeBuilderConfig(**options: Any)

Bases: Config

common base class for config of runtime builders

classmethod get_options() → Dict[Any, Any]

Override this classmethod to provide extra config arguments.

class testplan.common.remote.remote_runtime.SourceTransferBuilder(**options: Any)

Bases: RuntimeBuilder

source-code-based remote python runtime environment builder, which would only transfer testplan source code to remote or reuse existing testplan source path on remote specified by user. certain sys.path manipulation should be performed by caller/children classes of RemoteResource accordingly.

Parameters:

• transfer_exclude – list of glob patterns to exclude from transfer

• python_bin – python binary to use on remote

• existing_testplan_parent – user-specified existing testplan parent directory on remote, if specified local testplan source code would not be transferred to remote

CONFIG

alias of SourceTransferBuilderConfig

bootstrap(*args: Any, **kwargs: Any) → None

runtime initialization with info from parent RemoteResource

get_remote_rpyc_bin() → str

return rpyc binary path on remote side

local_export_pyenv() → List[Tuple[str, str]]

export pyenv on local side, return a list of (local_path, remote_path) pairs that need to be transferred to remote side

remote_prepare_pybin() → str

prepare pybin on remote side

Returns:

python binary path on remote to be used to execute tests

remote_setup_pyenv(remote_paths: List[str]) → str

setup pyenv on remote side

Parameters:

remote_paths – list of paths on remote that are transferred from local

Returns:

path to testplan parent dir on remote, for sys.path alteration

remote_teardown_pyenv() → None

teardown pyenv on remote side

class testplan.common.remote.remote_runtime.SourceTransferBuilderConfig(**options: Any)

Bases: RuntimeBuilderConfig

config class for SimpleSyspathBuilder

classmethod get_options() → Dict[Any, Any]

Override this classmethod to provide extra config arguments.

testplan.common.remote.remote_service module

Module implementing RemoteService class. Based on RPyC package.

class testplan.common.remote.remote_service.RemoteService(name: str, remote_host: str, rpyc_bin: str | None = None, rpyc_port: int = 0, stop_timeout: float = 5, **options: Any)

Bases: Resource, RemoteResource

Spawns RPyC service on remote host via ssh and create RPyC connection for remote drivers.

Parameters:

• name – Name of the remote service.

• remote_host – Remote host name or IP address.

• rpyc_bin – Location of rpyc_classic.py script

• rpyc_port – Specific port for rpyc connection on the remote host. Defaults to 0 which start the rpyc server on a random port.

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

Also inherits all Resource and RemoteResource options

CONFIG

alias of RemoteServiceConfig

post_start() → None

After service is started.

post_stop() → None

After stopping the service.

pre_start() → None

Before service start.

pre_stop() → None

Before stopping the service.

starting() → None

Starting the rpyc service on remote host.

stopping() → None

Stops remote rpyc process.

uid() → str

Unique identifier.

class testplan.common.remote.remote_service.RemoteServiceConfig(**options: Any)

Bases: ResourceConfig, RemoteResourceConfig

Configuration object for RemoteService entity.

classmethod get_options() → Dict[Any, Any]

Resource specific config options.

testplan.common.remote.remote_driver module

class testplan.common.remote.remote_driver.RemoteDriver(remote_service, driver_cls, **options)

Bases: object

A proxy object that forwards access of itself to the actual driver that runs on remote host via the remote_service’s rpyc connection.

Parameters:

• remote_service (RemoteService) – the remote_service object to use

• driver_class (class) – the class of the driver to instantiate on remote host

Also takes all driver_class’s options.

testplan.common.remote.ssh_client module

Module containing SSH client functionality for remote operations.

class testplan.common.remote.ssh_client.SSHClient(host: str, port: int = 22, logger: Logger | None = None, **args: Any)

Bases: object

SSH client for remote operations including file transfers and command execution. Wraps paramiko functionality in a convenient interface.

close() → None

Close the SSH and SFTP connections.

Returns:

None

connect() → SSHClient

Establish an SSH connection.

Returns:

Self for method chaining

Return type:

SSHClient

exec_command(cmd: str | List[str], label: str | None = None, check: bool = True, env: Dict[str, Any] | None = None, timeout: int = 30) → Tuple[int, str, str]

Run a command on the remote host.

Parameters:

• cmd (str or List[str]) – Command to execute (either a string or list of arguments)

• label (str or NoneType) – Label for identifying the command in logs (defaults to hash of command)

• check (bool) – If True, raises exception when command fails

• env (Dict or NoneType) – Environment variables to set for the command.

• timeout (int) – Timeout for command execution in seconds

Returns:

Tuple of (exit_code, stdout_str, stderr_str)

Return type:

tuple of (int, str, str)

Raises:

RuntimeError if command fails and check is True

listdir_iter(path: str) → Any

List files in a directory on the remote host.

Parameters:

path (str) – Path to the directory to list

Returns:

Generator yielding file names in the directory

Return type:

generator of str

open_file(path: str, mode: str) → SFTPFile

Open a file on the remote host using SFTP.

Parameters:

• path (str) – Path to the file to open

• mode (str) – Mode in which to open the file (e.g., ‘r’, ‘w’, ‘rb’)

Returns:

File object for the remote file

Return type:

paramiko.sftp_file.SFTPFile

open_sftp() → SFTPClient

Open an SFTP session.

Returns:

SFTP client object

Return type:

paramiko.sftp_client.SFTPClient

property sftp_client: SFTPClient

Get the underlying paramiko SFTP client.

Returns:

Paramiko SFTP client instance

Return type:

paramiko.sftp_client.SFTPClient

property ssh_client: SSHClient

Get the underlying paramiko SSH client.

Returns:

Paramiko SSH client instance

Return type:

paramiko.SSHClient

Module contents