Workflow guides13Testing and Running

Using riscos-build-run

riscos-build-run is the high-level interface to the remote build service. It takes files or directories from the host project, uploads them, runs one or more RISC OS commands remotely, and can return files or directories when the run completes.

Each run uses a fresh temporary environment. Files are not copied automatically; every required file or directory must be listed explicitly on the command line.

The simplest remote execution case is a previously built command. A single uploaded file is always placed in the root of the remote work area, so the remote command names the leafname directly, not the host subdirectory it came from:

riscos-build-run aif32/CLITool,ff8 --command CLITool

Textual BBC BASIC programs can be run in the same way, using the host filename with its ,fd1 suffix in the upload list and the RISC OS leafname in the remote command:

riscos-build-run TestProgram,fd1 --command "Run TestProgram"

Video 7 of Video walkthroughs works through a BASIC program this way end to end, including error handling, on-screen drawing, and a captured screenshot.

Commands, returns, and timeouts

The most important options are:

• --command to specify RISC OS commands to run;
• --return-file or --return-dir to collect results;
• --return-to to control the host output location;
• --timeout to avoid hung runs;
• --32, --64, or --arch to choose the architecture.

Returning a built artifact from a remote run looks like this. Two details matter here: a trailing slash on the uploaded directory flattens its contents into the remote work root (so amu finds the makefile without an explicit Dir first), and --return-file takes a RISC OS-style dotted path, not a host-style path with slashes:

riscos-build-run mysource/ --command 'amu' --return-file rm32.MyModule,ffa --return-to MyModule,ffa

...

MyModule: Module built {RAM}

Result file: filetype=&ffa, 6012 bytes

Without the trailing slash, mysource itself becomes a subdirectory of the remote work root, so amu would need an explicit Dir mysource command first; and a slash-style rm32/MyModule,ffa for --return-file is reported as not found even when the file genuinely exists, because the remote side resolves it as a RISC OS path.

The same return mechanism is useful for files written by a BASIC program, such as a generated report. Here results has no path separator, so the upload and dotted-path concerns above do not apply:

riscos-build-run TestProgram,fd1 --command "Run TestProgram" --return-file results --return-to results,fff

Result file: filetype=&fff, 18 bytes

Using .robuild.yaml

For more complex build-service jobs, a project may include a .robuild.yaml file. When that file is included in the upload set, its commands replace the need to specify multiple --command options manually.

For integration with GitHub CI workflows, see Appendix Y: GitHub CI Actions which describes the gerph/riscos-build-service-action.

Tooltester

riscos-tooltester is a separate local integration-test tool for command-line programs. It reads a plain text script, runs the tool under test, captures output, checks return codes, and compares the results to expected output files. It is a good fit for deterministic command-line tools whose behaviour is easiest to validate from their command line interface.

A typical local test run is:

riscos-tooltester mytool tests

Basic command-line behaviour:

  Help text                          : OK

  Version text                       : OK



-----------

Pass:       2

Fail:       0

Crash:      0

Skip:       0

The tool path must still resolve after riscos-tooltester changes directory. Each test command runs with the current directory changed to the test directory (tests/ above), so a bare relative name such as mytool only works if it happens to be on PATH. A tool sitting next to the test directory needs an absolute path, or a path relative to the test directory such as ../mytool; otherwise every test crashes with Expected RC 0, got 128 rather than running the tool at all.

By default the test directory is expected to contain a tests.txt script, one or more expected output files, and any input data required by the tests. The script is line-oriented: groups define shared defaults, tests inherit those defaults, and individual statements describe the command line, expected return code, expected output, and any files or directories that should be created or removed.

A small but practical layout often looks like this:

tests/

  tests.txt

  expect/

    help-output

    version-output

    shared_replacements

  testdata/

    sample-input.txt

For a tool that has a few simple modes, it is usually enough to share one group-level command and vary only the arguments and expectations per test:

Group: Basic command-line behaviour

Command: $TOOL $ARGS

Replace: expect/shared_replacements



Test: Help text

Args: --help

Expect: expect/help-output



Test: Version text

Args: --version

Expect: expect/version-output

Use -group and -test to narrow a run to one subset while you are iterating, and add -show-command, -show-output, or -show-diff when diagnosing a mismatch. When output differs from the expected file, the normalised actual output is written beside the expectation with -actual appended to the filename.

For the full script and replacement-file syntax, see Appendix W: riscos-tooltester file format.

Common failure modes

Common problems in remote execution are:

• forgetting to upload a file or directory needed by the run;
• using host filename syntax in a RISC OS command where the RISC OS name is required;
• missing timeout protection on a command that may wait for input;
• asking for a returned file without also naming where it should be written on the host.