Documentation/dev-tools/ktap.rst

Source file repositories/reference/linux-study-clean/Documentation/dev-tools/ktap.rst

File Facts

System
Linux kernel
Corpus path
Documentation/dev-tools/ktap.rst
Extension
.rst
Size
11415 bytes
Lines
315
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0

===================================================
The Kernel Test Anything Protocol (KTAP), version 1
===================================================

TAP, or the Test Anything Protocol is a format for specifying test results used
by a number of projects. Its website and specification are found at this `link
<https://testanything.org/>`_. The Linux Kernel largely uses TAP output for test
results. However, Kernel testing frameworks have special needs for test results
which don't align with the original TAP specification. Thus, a "Kernel TAP"
(KTAP) format is specified to extend and alter TAP to support these use-cases.
This specification describes the generally accepted format of KTAP as it is
currently used in the kernel.

KTAP test results describe a series of tests (which may be nested: i.e., test
can have subtests), each of which can contain both diagnostic data -- e.g., log
lines -- and a final result. The test structure and results are
machine-readable, whereas the diagnostic data is unstructured and is there to
aid human debugging.

KTAP output is built from four different types of lines:

- Version lines
- Plan lines
- Test case result lines
- Diagnostic lines

In general, valid KTAP output should also form valid TAP output, but some
information, in particular nested test results, may be lost. Also note that
there is a stagnant draft specification for TAP14, KTAP diverges from this in
a couple of places (notably the "Subtest" header), which are described where
relevant later in this document.

Version lines
-------------

All KTAP-formatted results begin with a "version line" which specifies which
version of the (K)TAP standard the result is compliant with.

For example:

- "KTAP version 1"
- "TAP version 13"
- "TAP version 14"

Note that, in KTAP, subtests also begin with a version line, which denotes the
start of the nested test results. This differs from TAP14, which uses a
separate "Subtest" line.

While, going forward, "KTAP version 1" should be used by compliant tests, it
is expected that most parsers and other tooling will accept the other versions
listed here for compatibility with existing tests and frameworks.

Plan lines
----------

A test plan provides the number of tests (or subtests) in the KTAP output.

Plan lines must follow the format of "1..N" where N is the number of tests or subtests.
Plan lines follow version lines to indicate the number of nested tests.

While there are cases where the number of tests is not known in advance -- in
which case the test plan may be omitted -- it is strongly recommended one is
present where possible.

Test case result lines
----------------------

Test case result lines indicate the final status of a test.

Annotation

Implementation Notes