ATF-FORMATS(5) | File Formats Manual | ATF-FORMATS(5) |
atf-formats
—
machine-parseable data formats used by ATF
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.
Atffiles are logically divided into three sections:
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:
An example:
prop: test-suite = utilities conf: unprivileged-user = nobody tp: t_cp tp: t_mv tp: t_df tp-glob: t_dir_*
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.
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:
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
December 20, 2011 | NetBSD 10.99 |