Various testcases.

tbot_contrib.utils.ensure_sd_unit(lnx: LinuxShell, services: List[str]) None[source]

check if all systemd services in list services run on linux machine lnx. If not, try to start them.

  • lnx – linux shell

  • services – list of systemd services

New in version 0.8.3.

tbot_contrib.utils.find_ip_address(lnx: LinuxShell, route_target: str | None = None, force: bool = False) str[source]

Find out an IP-address of a host.

In times where most hosts have many IP addresses, this is not as trivial as one would like. This testcase approaches the problem by trying to find the IP-address, the host would use on a certain route.

By default, this is the route to reach a theoretical host at This will yield a sensible result in most cases but of course will not always be the address you want. For more fine-grained control you can pass a route_target. This is the IP-address of this theoretical host to reach.

  • lnx (linux.LinuxShell) – The host to work on.

  • route_target (str) – An optional route target. Defaults to

  • force (bool) – By default, this testcase caches results for faster lookup when called multiple times. This parameter enforces a re-check which might be useful when the network configuration on lnx changed.

Return type:



The IP-address which was found.

New in version 0.8.3.

Changed in version 0.9.2: Fixed find_ip_address() not working properly when the route target is a local address.

tbot_contrib.utils.hashcmp(a: Path, b: Path) bool[source]

Compare the hashsum of two files (potentially from different hosts).

hashcmp() automatically selects a hash-summing tool which is available on both hosts and uses it to compare the checksum of the two files. It returns True if they match and False otherwise. If one of the files does not exist, False is returned.

New in version 0.9.2.

tbot_contrib.utils.copy_to_dir(sources: Path[H1], dest_dir: Path[H2], *, hashcmp: bool = False) Path[H2][source]
tbot_contrib.utils.copy_to_dir(sources: Iterable[Path[H1]], dest_dir: Path[H2], *, hashcmp: bool = False) List[Path[H2]]

Copy one or more files to a directory

This function will copy each file from sources into a new file in dest_dir which has the same name as the original one.

This function uses linux.copy() under the hood so sources and dest_dir need not be on the same host. See that function for details.

  • sources – The file(s) to copy. This may be a single Path or an iterable which yields zero or more Path objects.

  • dest_dir (linux.Path) – The target directory where the files should be copied to. It does not need to be on the same host as sources.

  • hashcmp (bool) – This optional named argument can be set to true to make the function verify checksums of each file before performing the copy. This is very useful to skip superfluous copying operations.


If a single sources path was passed, a single path is returned which points to the newly created copy. If multiple sources were passed (as an iterable), a list of paths for each copied file is returned.

New in version 0.10.2.

Example: Copy a file from lab-host to a tftp-server for serving it to a target device.

from tbot_contrib import utils

linux_sources = lh.workdir / "linux"

tftp_zimage = utils.copy_to_dir(
    linux_sources / "arch/arm/boot/zImage",

tftp_filename = tftp_zimage.name

u_boot.exec0("tftp", "0x10000000", f"{tftp_server.addr}:{tftp_filename}")

Example: Copy many files from lab-host to a tftp-server for serving them to a target device.

from tbot_contrib import utils

linux_sources = lh.workdir / "linux"

        linux_sources / "arch/arm/boot/zImage",
        linux_sources / "arch/arm/boot/dts/mydevice.dtb",

Example: Copy all config files to a new directory and then run a replacement command on each one.

from tbot_contrib import utils

config_dir = lnx.fsroot / "etc" / "myapp"
newconfig_dir = lnx.workdir / "newconfig"
lnx.exec0("rm", "-rf", newconfig_dir)
lnx.exec0("mkdir", newconfig_dir)

new_cfg_files = utils.copy_to_dir(

for cfg_file in new_cfg_files:
    lnx.exec0("sed", "-i", "s/eth0/wlan0/g", cfg_file)
tbot_contrib.utils.find_block_partitions(dev: Path[H], *, include_self: bool = False) Iterator[Path[H]][source]

Find all partitions of a given block device.

  • dev (linux.Path) – The block device whose partitions should be found.

  • include_self (bool) – Whether to include the block device itself in the partition list as well. Defaults to False.


An iterator over path objects for all partitions of the block device.

New in version 0.10.5.

Example: Unmount all partitions before writing a new image to the device.

from tbot_contrib import utils

blkdev = lnx.fsroot / "dev" / "sdb"
for part in utils.find_block_partitions(blkdev):
    # Ignore errors...
    lnx.exec("umount", part)
tbot_contrib.utils.strip_ansi_escapes(s: str) str[source]

Strip all ANSI escape sequences from a string

This helper can be used when programs have colored output and piping with | cat doesn’t help (e.g. forced color as with --color=always).

New in version 0.9.2.