Retro Reference Test Case Specification 1.0: RetroGTK Reference Manual

## Retro Reference Test Case Specification 1.0 |

### Introduction

This is the first version of the reference test case specification used by `retro-reftest`. These test cases will run a series of interdependent smaller tests on a Libretro core to ensure it behaves as expected.

### The Tests

The tests are based on the Glib test framework, as such they must have a path describing the test which will be used as the root for all the tests it runs.

First, the fllowing tests will be run in this order:

- `Boot`: Tests loading the core with the optional medias and booting it.
- `Options`: If options are specified, tests that the ones offered by the core are as expected.

Then the following tests will be run on specific frames:

- `FastForward`: If there is a gap between the last ran frame and the frame to run, quickly run all the inbetween frames.
- One of the following state tests can be run:
  - `State None`: If specified, will test that no state can be accessed.
  - `State Refresh`: If specified, will test that the sate can be accessed by saving and instantaneously reloading it.
- `Run`: Will run the frame.
- `Video`: If specified, will test that the video output is as expected.

### Basic Format of the File

The basic format of the file is the same as the Freedesktop desktop entries, which is implemented in the Glib as GKeyFile.

### Recognized Keys

#### Retro Reftest

Key | Value Type | Required | Description
Path | string | Yes | The test path as understood by the Glib test framework to be used as the root for the test paths of this test case.
Core | string | Yes | The path (absolute or relative to this file's location) to the Libretro core's module.
Medias | string(s) | No | A list of media paths (absolute or relative to this file's location) to be loaded by the core.

#### Options

If this group is present, the `Options` test will be added. This group lists the expected options set by the tested Libretro core via `RETRO_ENVIRONMENT_SET_VARIABLES`, the keys correspond to these options’ keys and the values are string lists listing the available values. To check that the core has no option, add an empty `Options` group.

#### Frames

Key | Value Type | Required | Description
State | string | No | One of `None` or `Refresh`.
Video | string | No | The path (absolute or relative to this file's location) to the expected video output image.

### Example

An example test case for a test core and its expected output:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    [Retro Reftest]
    Path=/test
    Core=/app/lib/libretro/test_libretro.so

    [Options]
    test_aspect=4:3;16:9;
    test_samplerate=30000;20000;
    test_opt0=false;true;
    test_opt1=0;
    test_opt2=0;1;foo;3;

    [Frame 0]
    State=Refresh
    Video=test.png

    1
    2
    3
    4
    5
    /test/Boot: OK
    /test/Options: OK
    /test/0/State Refresh: OK
    /test/0/Run: OK
    /test/0/Video: OK

An example test case for a Sega Genesis emulator and its expected output:

    1
    2
    3
    4
    5
    6
    7
    [Retro Reftest]
    Path=/blastem/240pSuite
    Core=/app/lib/libretro/blastem_libretro.so
    Medias=240pTestSuite-v15.gen;

    [Frame 150]
    Video=blastem.240pSuite.150.png

    1
    2
    3
    4
    /blastem/240pSuite/Boot: OK
    /blastem/240pSuite/150/FastForward: OK
    /blastem/240pSuite/150/Run: OK
    /blastem/240pSuite/150/Video: OK

### References

- The desktop entry specification