Appendix57Appendix W: riscos-tooltester file format

Suite layout and defaults

The normal suite entry point is a file named tests.txt in the chosen test directory, though the runner can be pointed at a different file with -script. A suite directory commonly contains:

• one main script file, usually tests.txt;
• expected output files, often under expect/;
• replacement scripts used to normalise unstable output before comparison; and
• optional input data files, often under testdata/.

The script is read line by line. Blank lines and lines beginning with # are ignored.

Statement syntax

Each statement has one of these forms:

Keyword: value

Checker:parameter: value

-Keyword:

-Checker:parameter:

The two structural statements are:

To clear an inherited value from the current group, write the same keyword with a leading minus and no value, such as -Expect: or -Creates:.

Core suite commands

The runner accepts the following built-in suite statements:

Substitution variables

Most statement values may contain substitution variables. The runner expands the following names:

Quoted argument text in Args: is preserved when the numbered $ARGn variables are extracted, so embedded spaces can still be treated as one argument.

Only $ARG1 through $ARG9 are ever defined; a tenth or later argument is simply not made available through a numbered variable. Writing $ARG10 in a command does not fall back to $ARG1 followed by a literal 0: the substitution logic greedily matches as many digits as possible when looking for a variable name, so it treats the whole of ARG10 as the candidate name, finds no such variable, and leaves $ARG10 in the command unsubstituted. A test needing a tenth or later argument should pass it through $ARGS instead and split it within the tested command.

Checker commands

Checker statements use the form <checker>:<parameter>: <value>. They attach extra validation rules to the current group or test and are typically used with one file named by Creates:. The runner currently supports the following checker families:

<offset> [word|byte|string]: <value>

The installed runner does not permit checker use with more than one created file in the same test. If you need checker validation for multiple outputs, split them into separate tests.

Replacement script language

Replacement scripts are miniature line-processing programs. They transform the captured output into a stable form before it is compared against the expectation file, which is useful when the tool prints variable data such as absolute paths, timestamps, branch names, or memory addresses.

The replacement file is read line by line:

• blank lines and comment lines beginning with # are ignored;
• directive lines begin with %;
• all other lines are rules made of zero or more conditions followed by one action.

/^Processing:/ d

s!/[^ ]+/testdata!TESTDATA!g

s/0x[0-9a-f]{8}/0xXXXXXXXX/gi

Worked suite example

A compact suite for command help and version output can be written like this:

Group: Core behaviour

Command: $TOOL $ARGS

Replace: expect/shared_replacements



Test: Help text

Args: --help

Expect: expect/help



Test: Version text

Args: --version

Expect: expect/version



Test: Writes report

Args: --report out.txt

Creates: out.txt

text:matches: expect/report

That pattern keeps the command line and shared replacements at group level, leaving each test to describe only the inputs and checks that differ.