LTP shell API

Shell API overview

First lines of the shell test should be a shebang, a license, and copyrights.

#!/bin/sh
# SPDX-License-Identifier: GPL-2.0-or-later
# Copyright 2099 Foo Bar <foo.bar@example.org>

A documentation comment block formatted in ReStructuredText should follow right after these lines. This comment is parsed and exported into the LTP documentation at https://linux-test-project.readthedocs.io/en/latest/users/test_catalog.html

# ---
# doc
# Test for a foo bar.
#
# This test is testing foo by checking that bar is doing xyz.
# ---

The shell loader test library uses the LTP C API internally by parsing a special JSON formatted comment and initializing it accordingly. The JSON format is nearly 1:1 serialization of the struct tst_test into a JSON. The environment must be always preset even when it’s empty.

# ---
# env
# {
#  "needs_root": true,
#  "needs_tmpdir": true,
#  "needs_kconfigs": ["CONFIG_NUMA=y"],
#  "tags": {
#   ["linux-git", "432fd03240fa"]
#  }
# }

After the documentation and environment has been laid out we finally import the tst_loader.sh. This will, among other things, start the tst_run_shell.c binary, that will parse the shell test environment comment and initialize the C test library accordingly.

. tst_loader.sh

At this point everything has been set up and we can finally write the test function. The test results are reported by the usual functions macro tst_res and macro tst_brk. As in the C API these functions store results into a piece of shared memory as soon as they return so there is no need to propagate results event from child processes.

tst_test()
{
     tst_res TPASS "Bar enabled Foo"
}

In order for the test to be actually executed the very last line of the script must source the tst_run.sh script.

. tst_run.sh

In order to run a test from a LTP tree a few directories has to be added to the $PATH. Note that the number of ../ may depend on the depth of the current directory relative to the LTP root.

$ PATH=$PATH:$PWD:$PWD/../../lib/ ./foo01.sh

Test setup and cleanup

The test setup and cleanup functions are optional and passed via variables. Similarly to the C API the setup is executed exactly once at the start of the test and the test cleanup is executed at the test end or when test was interrupted by macro tst_brk.

#!/bin/sh
# SPDX-License-Identifier: GPL-2.0-or-later
# Copyright (c) 2025 Petr Vorel <pvorel@suse.cz>
#
# ---
# env
# {
# }
# ---

TST_SETUP=setup
TST_CLEANUP=cleanup

. tst_loader.sh

setup()
{
	tst_res TINFO "setup executed"
}

cleanup()
{
	tst_res TINFO "Cleanup executed"
}

tst_test()
{
	tst_res TPASS "Test is executed"
}

. tst_run.sh