tbot is, for the most part, a library to interact with embedded devices and automate working with them. But it also ships with a CLI (commandline interface) tool which ties together code using tbot. Usage of this CLI is not at all mandatory, you can write your own scripts just as well. But the common interface has proven to be quite useful for larger projects.
Advantages of using tbot’s CLI are:
Easy mechanism to modularize configuration
Common command to call many different testcases
Provides commandline flags for common tbot debugging needs
The new CLI is called
newbot and this is what will be described in this
document. There is also an old tool called
tbot which will be
deprecated in a future release.
A gentle introduction can be found in the Quick Start guide. This document here serves as a reference documentation.
usage: tbot [options] [testcases ...] positional arguments: testcase testcases that should be run. options: -h, --help show this help message and exit -C WORKDIR use WORKDIR as working directory instead of the current directory. -c CONFIG, --config CONFIG -f FLAG set a user defined flag to change testcase behaviour -k, --keep-alive keep machines alive for later tests to reacquire them -v increase the verbosity -q decrease the verbosity --version show program's version number and exit
Testcases and configuration are specified as Python module paths. For
testcases, the last element is the testcase function to be called.
Configuration modules are expected to contain a
function which will be called to enable the config. This can be expressed in
some simple equivalent Python code. Calling
$ newbot -c config.my_config tc.examples.foo tc.interactive.linux
would, in simple terms, be equivalent to this:
# 1. load and enable config import config.my_config config.my_config.register_machines(tbot.ctx) # 2. run first testcase import tc.examples tc.examples.foo() # 3. run second testcase import tc.interactive tc.interactive.linux()
Flags are a mechanism to allow quickly switching settings in configuration or testcases. For example, a flag might be used to switch to booting from a different source.
All flags passed to
-f are added to the
tbot.flags set. Config and testcases can then check for them like
# Check if flag is present if "boot-nfs" in tbot.flags: bootargs = "root=/dev/nfs nfsroot=...,tcp,v3" else: bootargs = "root=/dev/mmcblk0p1" # Check if flag is absent if "silent-boot" not in tbot.flags: bootargs += " loglevel=7" uboot.env("bootargs", bootargs)
-k Keep Alive¶
By default, machine instances are “torn down” as soon as the outermost with-block which requested them ends. This means, that in the following code, the board is rebooted between the two blocks:
with tbot.ctx.request(tbot.role.BoardLinux) as lnx: lnx.exec0("echo", "first boot") with tbot.ctx.request(tbot.role.BoardLinux) as lnx: lnx.exec0("echo", "second boot")
However, this is often not ideal because it leads to excessively long testcase
run times. The
-k flag instead changes behaviour such that an instance is
“kept alive” until the very end of a
newbot run. Thus, the board would not
reboot in the above example.
To make testcases which require a powercycle still work, they should explicitly
request a reset. This way, it will work both with and without
with tbot.ctx.request(tbot.role.BoardLinux) as lnx: lnx.exec0("echo", "first boot") with tbot.ctx.request(tbot.role.BoardLinux, reset=True) as lnx: lnx.exec0("echo", "second boot")
You can read more about this in the Context documentation.
Verbose mode can be used to debug problems in lower layers of the communication. It shows all sent and received data on all “channels”. For example, when tbot doesn’t seem to recognize a login-prompt, this can help.
If you have previously written tbot code for the old
tbot CLI tool, this
section details how to migrate to
newbot. Before starting here, please
adjust your code for the Context API as detailed in
Migrating to Context.
newbot no longer supports the legacy style
From there, everything should be quite straight forward. The only thing which changes is the commandline syntax:
-bconfig arguments have been consolidated into a single
-cflag. Instead of paths, you now need to specify Python modules. So
Testcases are no longer “collected” from directories, they are now also imported using standard Python imports. A testcase called
test_uboot_emmcin a file
tc/uboot/tests.pywill now be called as
As this can get quite cumbersome to type, it is often a good idea to re-import testcases in a higher level module. For example you could add this line to
from .uboot.tests import test_uboot_emmc
And then call the testcase as