`tbot` Module¶

Warning

This is the documentation for an old version of tbot. Please head over to

https://tbot.tools/modules/main.html

for the latest docs!

tbot.testcase(tc: F) → F[source]¶

Decorate a function to make it a testcase.

Example:

@tbot.testcase
def foobar_testcase(x: str) -> int:
    return int(x, 16)

tbot.named_testcase(name: str) → Callable[[F], F][source]¶

Decorate a function to make it a testcase, but with a different name.

The testcase’s name is relevant for log-events and when calling it from the commandline.

Example:

@tbot.named_testcase("my_different_testcase")
def foobar_testcase(x: str) -> int:
    return int(x, 16)

(On the commandline you’ll have to run tbot my_different_testcase now.)

tbot.acquire_lab() → tbot.selectable.LabHost[source]¶

Acquire a new connection to the LabHost.

If your LabHost is a SSHLabHost this will create a new ssh connection.

You should call this function as little as possible, because it can be very slow. If possible, try to reuse the labhost. A recipe for doing so is:

import typing
import tbot
from tbot.machine import linux

@tbot.testcase
def my_testcase(
    lab: typing.Optional[linux.LabHost] = None,
) -> None:
    with lab or tbot.acquire_lab() as lh:
        # Your code goes here
        ...

Return type: tbot.machine.linux.LabHost

tbot.acquire_local() → tbot.machine.linux.lab.local.LocalLabHost[source]¶

Acquire a machine for the local host.

Localhost machines are very cheap so they do not need to be shared like the others and you can create as many as you want. One usecase might be copying test-results to you local machine after the run.

Example:

import tbot

@tbot.testcase
def my_testcase() -> None:
    with tbot.acquire_local() as lo:
        lo.exec0("id", "-un")
        # On local machines you can access tbot's working directory:
        tbot.log.message(f"CWD: {lo.tbotdir}")

tbot.acquire_board(lh: tbot.selectable.LabHost) → tbot.selectable.Board[source]¶

Acquire a handle to the selected board.

The returned board must be used in a with statement to be powered on.

Return type: tbot.machine.board.Board

tbot.acquire_uboot(board: tbot.selectable.Board) → tbot.selectable.UBootMachine[source]¶

Acquire the board’s U-Boot shell.

As there can only be one instance of UBootMachine at a time, your testcases should optionally take the UBootMachine as a parameter. The recipe looks like this:

import contextlib
import typing
import tbot
from tbot.machine import board


@tbot.testcase
def my_testcase(
    lab: typing.Optional[tbot.selectable.LabHost] = None,
    uboot: typing.Optional[board.UBootMachine] = None,
) -> None:
    with contextlib.ExitStack() as cx:
        lh = cx.enter_context(lab or tbot.acquire_lab())
        if uboot is not None:
            ub = uboot
        else:
            b = cx.enter_context(tbot.acquire_board(lh))
            ub = cx.enter_context(tbot.acquire_uboot(b))

        ...

Return type: tbot.machine.board.UBootMachine

tbot.acquire_linux(b: Union[tbot.selectable.Board, tbot.selectable.UBootMachine]) → tbot.selectable.LinuxMachine[source]¶

Acquire the board’s Linux shell.

Can either boot from a previously created U-Boot (if the implementation supports this) or directly.

To write testcases that work both from the commandline and when called from other testcases, use the following recipe:

import contextlib
import typing
import tbot
from tbot.machine import board


@tbot.testcase
def test_testcase(
    lab: typing.Optional[tbot.selectable.LabHost] = None,
    board_linux: typing.Optional[board.LinuxMachine] = None,
) -> None:
    with contextlib.ExitStack() as cx:
        lh = cx.enter_context(lab or tbot.acquire_lab())
        if board_linux is not None:
            lnx = board_linux
        else:
            b = cx.enter_context(tbot.acquire_board(lh))
            lnx = cx.enter_context(tbot.acquire_linux(b))

        ...

Return type: tbot.machine.board.LinuxMachine

tbot.flags¶

Flags that were set on the commandline using -f <flagname>

Check for a flag using:

if "flagname" in tbot.flags:
    ...

`tbot.selectable`¶

class tbot.selectable.LabHost[source]¶

Bases: tbot.machine.linux.lab.local.LocalLabHost, contextlib.AbstractContextManager, typing.Generic

Default LabHost type.

Might be replaced by another LabHost if one was selected on the commandline using -l <lab.py>

Create a new instance of a LocalLabHost.

class tbot.selectable.Board(lh: tbot.machine.linux.lab.machine.LabHost)[source]¶

Bases: tbot.machine.board.board.Board, contextlib.AbstractContextManager, typing.Generic

Dummy type that will be replaced by the actual selected board at runtime.

Initialize an instance of this board.

This will not yet power on the board. For that you need to use a with block:

with MyBoard(lh) as b:
    ...

Parameters: lh (tbot.machine.linux.LabHost) – LabHost from where to connect to the Board.

class tbot.selectable.UBootMachine(b: Any)[source]¶

Bases: tbot.machine.board.uboot.UBootMachine, contextlib.AbstractContextManager, typing.Generic

Dummy type that will be replaced by the actual selected U-Boot machine at runtime.

Create a new board machine.

Parameters: board (tbot.machine.board.Board) – The board this machine should use.

class tbot.selectable.LinuxMachine(b: Any)[source]¶

Bases: tbot.machine.board.linux.LinuxStandaloneMachine, contextlib.AbstractContextManager, typing.Generic

Dummy type that will be replaced by the actual selected Linux machine at runtime.

Create a new instance of this LinuxMachine.

`tbot.log`¶

class tbot.log.EventIO(ty: List[str], initial: Union[str, tbot.log._C, termcolor2._C, None] = None, *, verbosity: tbot.log.Verbosity = <Verbosity.INFO: 1>, nest_first: Optional[str] = None, **kwargs: Any)[source]¶

Bases: _io.StringIO

Stream for a log event.

Create a log event.

A log event is a io.StringIO and everything written to the stram will be added to the log event.

Parameters: initial (str) – Optional first line of the log event

Helpers¶

log.IS_UNICODE = True¶

Boolean that is set if stdout supports unicode.

You should use tbot.log.u() instead of querying this flag.

log.IS_COLOR = True¶

Boolean that is set if tbot’s output should be colored.

You can use tbot.log.c as an easy way to colorize your strings.

tbot.log.u(with_unicode: str, without_unicode: str) → str[source]¶

Select a string depending on whether the terminal supports unicode.

Parameters

with_unicode (str) – The string to be used if unicode is available
without_unicode (str) – The string to be used if unicode is not available

Return type

str

Returns

The selected string

class tbot.log.c(s: str) → tbot.log.c¶

Color a string. Reexport from termcolor2

Example:

tbot.log.message(tbot.log.c("Message").yellow.bold + ": Hello World!")

Parameters: s (str) – The string that should be colored

red¶: Set the foreground-color to red

green¶: Set the foreground-color to green

yellow¶: Set the foreground-color to yellow

blue¶: Set the foreground-color to blue

magenta¶: Set the foreground-color to magenta

cyan¶: Set the foreground-color to cyan

white¶: Set the foreground-color to white

on_red¶: Set the background-color to red

on_green¶: Set the background-color to green

on_yellow¶: Set the background-color to yellow

on_blue¶: Set the background-color to blue

on_magenta¶: Set the background-color to magenta

on_cyan¶: Set the background-color to cyan

on_white¶: Set the background-color to white

bold¶: Enable the bold attribute

dark¶: Enable the dark attribute

underline¶: Enable the underline attribute

blink¶: Enable the blink attribute

reverse¶: Enable the reverse attribute

concealed¶: Enable the concealed attribute

Log Events¶

tbot.log.message(msg: Union[str, tbot.log._C, termcolor2._C], verbosity: tbot.log.Verbosity = <Verbosity.INFO: 1>) → tbot.log.EventIO[source]¶

Log a message.

Parameters

msg (str) – The message
verbosity (Verbosity) – Message verbosity

tbot.log_event.command(mach: str, cmd: str) → tbot.log.EventIO[source]¶

Log a command’s execution.

Parameters

mach (str) – Name of the machine the command is run on
cmd (str) – The command itself

Return type

EventIO

Returns

A stream that the output of the command should be written to.

tbot.log_event.testcase_begin(name: str) → None[source]¶

Log a testcase’s beginning.

Parameters: name (str) – Name of the testcase

tbot.log_event.testcase_end(name: str, duration: float, success: bool = True) → None[source]¶

Log a testcase’s end.

Parameters

duration (float) – Time passed while this testcase ran
success (bool) – Whether the testcase succeeded

tbot Module¶

tbot.selectable¶

tbot.log¶

Helpers¶

Log Events¶

`tbot` Module¶

`tbot.selectable`¶

`tbot.log`¶