waft.system.nodes.base_node module

class waft.system.nodes.base_node.BaseNode(client: ClientBase)

Bases: ABC

Base class for all nodes

add_to_path(path: str | PurePath)

Add given path to PATH environment variable on node

Parameters:

path – Path to add to PATH environment variable

property architecture: NodeArchitecture

Return the Enum value representing the architecture type of the system

await_system_restart(seconds: int)

Await system restart.

Parameters:

seconds (int) – Time (in seconds) before the restart occurs.

chmod(filepath: PurePath, permissions: int)

Change owner of file

Parameters:

• filepath – Path to file for which to change owner

• permissions – Integer representation of permissions to set for file (ex. 777 for rwx permissions for all users and groups)

chown(filepath: PurePath, owner: str, recursive: bool = False)

Change owner of file

Parameters:

• filepath – Path to file for which to change owner

• owner – New owner for file in question

• recursive – Operate on files and directories recursively

clone_ssh_key_auth(username: str)

Clone SSH key authorization to another system user account.

Parameters:

username (str) – Target system account username

abstractmethod copy_file(path_from: PurePath, path_to: PurePath)

Copy a file

create_user(username: str, password: str | None = None) → str

Create a system user account.

Parameters:

• username (str) – New system account username

• password (Optional[str]) – New user’s password. Defaults to existing user’s password or a new system generated value.

Returns:

Password for the new user account

Return type:

str

abstractmethod directory_exists(directory: PurePath) → bool

Check if the given directory exists on the node and return boolean value

Parameters:

directory – Directory path to check exists

abstractmethod file_exists(path_from: PurePath)

Check to see that a file exists or not

generate_password(length=20) → str

Generate a random password string.

Returns:

password

Return type:

str

abstractmethod get_dns_server_addresses() → set[str]

Get the IP addresses of the currently configured DNS servers.

Returns:

Set of DNS server addresses

Return type:

set[str]

abstractmethod get_domain_ips(domain: str) → List[IPv4Address | IPv6Address]

Get IPv4 and IPv6 addresses for a domain and its www subdomain.

Parameters:

domain (str) – The domain to resolve.

Returns:

A list of IPs

Return type:

List

get_network_route(ip_address: str, optional_params: List[str] | None = None) → str

Retrieve the network route to a specified IP address from the node system.

This method uses the platform’s network trace command to find the node’s network path to the given IP address.

Parameters:

• ip_address (str) – The IP address for which to find the network route.

• optional_params (Optional[List[str]]) – Additional optional parameters for the trace command.

Returns:

The output from the trace command.

Return type:

str

abstractmethod get_sha256_of_file(remote_file_path: PurePath) → str | None

Get the sha256 of the file

abstractmethod getenv(key: str, default: Any = None) → Any

Return an environment variable value.

Parameters:

• key (str) – Environment variable name

• default (Any, optional) – Value to return if variable is not set. Defaults to None.

Returns:

environment variable value

Return type:

Any

abstract property home_dir: str

Return the full path to the home directory of the user on the current node

property hostname: str

Returns the hostname of the system

inline_ssh_env: bool = False

install_curl()

Install curl on the node

install_packages(package_names: list[str], arguments: List[str] | None = None)

Install packages with given names

Parameters:

• package_names – List of names of packages to be installed

• arguments – Optional list of additional arguments to be passed to package manager

install_playwright_deps()

Install playwright dependencies

install_python(version: str = '3.11.9')

Install python on node using package manager

install_python_module(module_name: str, version: str | None = None)

Install python module using available python package manager

Parameters:

• module_name – Name of module to install

• version – Version of python module to install

install_uv(version: str | None = None)

Install uv on the node

Parameters:

version (Optional[str]) – Specific uv version to install. Installs the latest by default.

install_wireless_networking()

Install configurable wireless networking components.

abstractmethod is_process_running(pid: str) → bool

Return boolean indicating if process with given PID is running

Parameters:

pid – Process ID to check if is running

is_python_installed(version: str | None = None, auto_raise: bool = False) → bool

Checks whether python (and optional version) is installed and properly added to path

Parameters:

• version (str) – Optional python version to check if installed

• auto_raise (bool) – True to raise an exception if python version is not found. False to return a boolean.

Returns:

True if python (and optional version) is installed and properly added to path

Return type:

bool

Raises:

RuntimeError – if auto_raise=True, python (and optional version) is not installed and properly added to path

is_service_running(service: str) → bool

Return boolean indicating if service of the given name is running

Parameters:

service – String name of the service to check if is running

keyring_exec(*args, secret: str | None = None) → str

Execute the keyring CLI.

Parameters:

• args (str) – Keyring command options to execute.

• secret (Optional[str]) – Secret input.

Returns:

Keyring command output.

Return type:

str

abstractmethod link_file(source_file: PurePath, target_file: PurePath, sudo: bool = False, link_type: Literal['symbolic', 'hard'] = 'hard')

Link file at given path

Parameters:

• source_file – Path to file to link

• target_file – Path to file to link to

• sudo – Boolean indicating if command should be run using sudo

• link_type – Link type

list_applications_matching_name(application_name: str)

List all the applications matching the name

abstractmethod make_directory(directory: PurePath, recursive: bool = False, sudo: bool = False)

Create given directory

Parameters:

• directory – Directory path to create

• recursive – If set to True all parent directories will be created as well

• sudo – If set to True the command will be run with sudo permissions

abstractmethod move_file(path_from: PurePath, path_to: PurePath)

Move a file

abstractmethod newest_file_in_dir(directory: PurePath, tstamp: Literal['atime', 'ctime', 'mtime']) → PurePath

Return the most recently modified file

Parameters:

• directory – PurePath object pointing to the directory in question

• tstamp – Type of timestamp to sort by

norm_path

Use this method to normalize a file path for the node. This is especially useful for windows nodes and how difficult paths are to deal with on windows

Parameters:

file_path – Full or partial file path part(s) to join

Returns:

Normalized path

Example input and output:

C:/folder\another_folder//file.txt -> C:folderanother_folderfile.txt

alias of PurePath

abstract property os_version: str

Returns the version of the OS e.g. 10.0.22631 N/A Build 22631

platform: Platforms

property platform_is_linux: bool

Return boolean indicating whether system is a Linux-based platform

Returns:

True if node is a Linux-based platform, False otherwise

Return type:

bool

property platform_is_macOS: bool

Return boolean indicating whether system is a macOS-based platform

Returns:

True if node is a macOS-based platform, False otherwise

Return type:

bool

property platform_is_unix: bool

Return boolean indicating whether system is a Unix-based platform

Returns:

True if node is a Unix-based platform, False otherwise

Return type:

bool

property platform_is_windows: bool

Return boolean indicating whether system is a Windows-based platform

Returns:

True if node is a Windows-based platform, False otherwise

Return type:

bool

python: str = 'python3'

abstractmethod read_file(file_path: str | PurePath, sudo: bool = False) → str

Read the contents of a remote file.

Parameters:

• file_path (str | PurePath) – Path of the file on the remote system to read

• sudo (bool) – If set to True the command will run with sudo permissions. Defaults to False.

Returns:

file contents

Return type:

str

abstractmethod remove_directory(directory: PurePath, recursive: bool = False)

Remove given directory

Parameters:

• directory – Directory path to remove

• recursive – If set to true all contained directories will be deleted as well, otherwise an exception will be raised if there are subdirectories

abstractmethod remove_file(filepath: PurePath, sudo: bool = False)

Remove file at the given path

Parameters:

• filepath – Path to file to be removed

• sudo – Should sudo be used when removing the file

resolve_dns_name(domain_name: str | None = None, type: str | None = None, extract: ResolveDnsNameExtractionTypes | None = None, **kwargs: Any) → Any

Generic DNS resolution method to be implemented by subclasses.

Parameters:

• domain_name – Optional domain name to resolve.

• type – Optional DNS record type (e.g., TXT).

• extract – Optional extraction flag.

• **kwargs – Arbitrary keyword arguments for further customization.

Returns:

DNS resolution output.

restart_process(process: str)

Restart process running on node

Parameters:

process – Process to be restarted

restart_ssh_server()

Restart SSH server on node

restart_system(delay: int = 0, wait: bool = True)

Restart the node operating system.

Parameters:

• delay (int, optional) – Time (in minutes) before the restart occurs. Defaults to 0.

• wait (bool, optional) – True to wait for the system restart to complete (default) or False not to wait.

abstractmethod run_background_command(command: List[str], sudo: bool = False)

Run a command in the background as a context manager

Parameters:

• command – List of strings to form the command to be run

• sudo – Run command with sudo permissions. On Windows this will be run with the “System” account

run_cdp_server()

Start a Chrome Debugging Protocol server on the test node

run_curl_command(curl_params: list, url: str, file_path: str | PurePath | None = None) → str

Run a curl command on a remote system

Parameters:

• curl_params – params for the curl command e.g. -fsSL

• url – Url to make the curl command to

• file_path – Optional path to save the output to

Returns: (str) ssh response output

run_msiexec_command(action: MsiAction, msi_path: str, properties: dict | None = None, quiet_mode: bool = True) → str

Execute msiexec command

run_ps_command(command: str, options: list[str] | None = None, auto_raise: bool = True) → str

Executes a PowerShell command on a remote Windows system and returns the output as a string.

Args:

command (str): PowerShell command to be executed remotely. options (Optional[list[str]]): PowerShell options to be executed remotely. auto_raise (bool): Boolean to raise a RuntimeError if all output is stderr and not stdout

Returns:

str: The output from the PowerShell command execution.

Raises:

Exception: Raises an exception if the command execution status is non-zero.

run_update()

Run updates on the system

set_system_environment_variable(variable: str, value: str | int)

Set Environment variable for entire system

Parameters:

• variable – name of the environment variable to set

• value – Value to which to set the environment variable

property simple_platform_string: Literal['linux', 'macOS', 'windows']

Returns basic string of platform name for simpler navigation of dictionaries

Returns:

One of ‘linux’, ‘macOS’, or ‘windows’ depending on platform information

Return type:

string

Raises:

ValueError – If the node is none of the expected platform types a ValueError will be raised

start_process(process: str)

Start process running on node

Parameters:

process – Process to be started

stop_process(process: str)

Stop process running on node

Parameters:

process – Process to be stopped

supports_sudo: bool = True

system_secret_del(identifier: str, username: str)

Delete a stored system secret.

Parameters:

• identifier (str) – Credential identifier.

• username (str) – Credential username.

system_secret_get(identifier: str, username: str) → dict

Retrieve a stored system secret.

Parameters:

• identifier (str) – Credential identifier.

• username (str) – Credential username.

Raises:

RuntimeError – if credential cannot be accessed

Returns:

Credential as a JSON dictionary

Return type:

dict

system_secret_set(identifier: str, username: str, secret: str)

Set a stored system secret.

Parameters:

• identifier (str) – Credential identifier.

• username (str) – Credential username.

• secret (str) – Credential secret.

abstract property system_type: str

Returns the system type or base architecture e.g. x64-based

property tmp_dir: PurePath

Define the temp directory of the node

abstractmethod touch_file(filepath: PurePath)

Touch file at given path

Parameters:

filepath – Path to file to touch

trace_cmd: str = ''

abstractmethod uninstall_package(package_name: str, full_purge: bool = True)

Uninstall package with given name

Parameters:

• package_name – String name of package to be uninstalled

• full_purge – Boolean indicating if all associated files should be removed upon uninstalling the package

property unsigned_certificate_in_chain: bool

Confirm that there is no self-signed certificate in the chain that will prevent registering node

property username: str

Returns the active username