ATF-FORMATS(5)

ATF-FORMATS(5) | File Formats Manual | ATF-FORMATS(5)

# NAME

`atf-formats` — machine-parseable data formats used by ATF

# DESCRIPTION

This manual page describes the multiple data formats used in ATF. These formats affect configuration files, control files and any data that is externalized or internalized by the tools.

Data files are always organized as follows:

    Header1: Value1            \
        ...                    | head
    HeaderN: ValueN            /
                               mandatory blank line
    Free-form text contents    \
        ...                    | body
        ...                    /

A file must always contain a ‘Content-Type’ header and must always separate that header from the body with a blank line, even if the body is empty.

The ‘Content-Type’ is always of the form:

    Content-Type: application/X-atf-<subtype>; version="<version>"

where ‘subtype’ indicates the specific file format and ‘version’ its format version. This header must be the first one of the file.

The main purpose of the ‘Content-Type’ header, aside from determining the format used in the file, is to allow future changes to a given format. Whenever an incompatible change is made, the version is bumped by one. By keeping the header in the first line, future versions may even remove the need for such a header -- e.g. if some format was replaced by XML files, which have their own mandatory header.

The rest of this document details the different format types.

## Format: application/X-atf-atffile, version: 1

Atffiles are logically divided into three sections:

- Test programs: the list of test programs that define the test suite described by the Atffile.
- Meta-data properties: these define some constant values applicable to all the test programs defined in the file. In some sense they define the properties that describe the test suite.
- Configuration variables: defaults for configuration variables that can be overridden through configuration files or the command line.

The grammar for Atffiles is the following:

    DATA ::= ( ( CONF | PROP | TP )? COMMENT? NEWLINE )* EOF
    CONF ::= 'conf:' WORD EQUAL STRING
    PROP ::= 'prop:' WORD EQUAL STRING
    TP ::= TPFILE | TPGLOB
    TPFILE ::= 'tp: ' STRING
    TPGLOB ::= 'tp-glob: ' STRING
    STRING ::= WORD | '"' WORD* '"'

The meaning of the constructions above is:

CONF
  Definition of a configuration variable.
PROP
  Definition of a meta-data property.
TPFILE
  Addition of a test program into the test suite. The string is taken literally as the program's name, and this program must exist.
TPGLOB
  Addition of multiple test programs into the test suite. The string is taken as a glob pattern, which may have or not have any matches in the current directory.

An example:

    prop: test-suite = utilities

    conf: unprivileged-user = nobody

    tp: t_cp
    tp: t_mv
    tp: t_df
    tp-glob: t_dir_*

## Format: application/X-atf-config, version: 1

Configuration files are very simple: they only contain a list of variable name/variable value pairs. Their grammar is:

    DATA ::= ( VAR? COMMENT? NEWLINE )* EOF
    VAR ::= WORD EQUAL STRING
    COMMENT ::= HASH WORD*
    STRING ::= WORD | '"' WORD* '"'

An example:

    # This is the system-wide configuration file for ATF.
    # The above and this line are comments placed on their own line.

    var1 = this is a variable value
    var2 = this is another one      # Optional comment at the end.

## Format: application/X-atf-tps, version: 3

The ‘application/X-atf-tps’ format multiplexes the standard output, standard error and results output streams from multiple test programs into a single data file. This format is used by atf-run(1) to report the execution of several test programs and is later parsed by atf-report(1) to inform the user of this process. It has the following grammar:

    DATA ::= INFO* TPS-COUNT TP-STANZA* INFO* EOF
    INFO ::= 'info' COLON STRING COMMA STRING NEWLINE
    TPS-COUNT ::= 'tps-count' COLON POSITIVE-NUMBER NEWLINE
    TP-STANZA ::= TP-START TC-STANZA* TC-END
    TP-START ::= 'tp-start' COLON TIMESTAMP COMMA STRING COMMA
                 POSITIVE-NUMBER NEWLINE
    TP-END ::= 'tc-end' COLON TIMESTAMP COMMA STRING (COMMA STRING)?
    TC-STANZA ::= TC-START (TC-SO | TC-SE)* TC-END
    TC-START ::= 'tc-start' COLON TIMESTAMP COMMA STRING NEWLINE
    TC-SO ::= 'tc-so' COLON STRING NEWLINE
    TC-SE ::= 'tc-se' COLON STRING NEWLINE
    TC-END ::= 'tc-end' COLON TIMESTAMP COMMA STRING COMMA TCR NEWLINE
    TCR ::= 'passed' | ('failed' | 'skipped') COMMA STRING
    TIMESTAMP ::= [0-9]+.[0-9]+

The meaning of the constructions above is:

TPS-COUNT
  Indicates the number of test programs that will be executed. There will be this exact amount of ‘TP-STANZA’ constructions following it.
TP-START
  Indicates the beginning of a test program. This includes the program's name and the amount of test cases that will follow.
TP-END
  Indicates the completion of a test program. This is followed by the program's name and, if the program ended prematurely, an error message indicating the reason of its failure. A successful execution of a test program (regardless of the status of its test cases) must not be accompanied by any reason.
TC-START
  Indicates the beginning of a test case. This is accompanied by the test case's name.
TC-SO
  Contains a text line sent to the standard output stream during the execution of the test case. Leading and trailing space is preserved.
TC-SE
  Contains a text line sent to the standard error stream during the execution of the test case. Leading and trailing space is preserved.
TC-END
  Indicates the completion of a test case. This is accompanied by the test case's name, its result and the reason associated with this result (if applicable).

An example:

    tps-count: 2
    tp-start: calculator, 1324318951.838923, 2
    tc-start: add, 1324318951.839101
    tc-end: add, 1324318951.839500, passed
    tc-start: subtract, 1324318951.840001
    tc-so: 3-2 expected to return 1 but got 0
    tc-end: subtract, 1324318952.000123, failed, Calculated an unexpected value
    tp-end: calculator, 1324318952.002301
    tp-start: files, 1, 1324318952.502348
    tc-start: copy, 1324318952.508291
    tc-se: could not find the cp(1) utility
    tc-end: copy, 1324318953.203145, skipped
    tp-end: files, 1324318953.203800

# SEE ALSO

atf(7)

December 20, 2011 | NetBSD 11.0